Directory example to not fail if no DB

Remove MariaDB from Docker compose file. Make it optional.
Adjust layout of stack traces to use dashes.
Do not capture stack trace in zap logger.

README.md

@@ -69,7 +69,7 @@ Go deep into the philosophy and implementation of `Microbus`:
 * [Unicast messaging](docs/tech/unicast.md) - Unicast enables bi-directional (request and response) HTTP-like messaging between a client and a single server over NATS
 * [HTTP ingress](docs/tech/httpingress.md) - The reason for and role of the HTTP ingress proxy service
 * [Encapsulation pattern](docs/tech/encapsulation.md) - The reasons for encapsulating third-party technologies
-* [Error capture](docs/tech/errorcapture.md) - How and why errors are captured and propagated across microservices boundaries
+* [Error capture](docs/tech/errorcapture.md) ✨ - How and why errors are captured and propagated across microservices boundaries
 * [Time budget](docs/tech/timebudget.md) - The proper way to manage request timeouts
 * [Configuration](docs/tech/configuration.md) - How to configure microservices
 * [NATS connection settings](docs/tech/natsconnection.md) - How to configure microservices to connect and authenticate to NATS

connector/logger.go

@@ -153,13 +153,16 @@ func (c *Connector) initLogger() (err error) {
  if env == LOCAL || env == TESTINGAPP {
  config = zap.NewDevelopmentConfig()
  config.EncoderConfig.EncodeTime = zapcore.TimeEncoderOfLayout("15:04:05.000")
+ config.DisableStacktrace = true
  // config.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
  } else if env == LAB {
  config = zap.NewProductionConfig()
  config.Level.SetLevel(zapcore.DebugLevel)
+ config.DisableStacktrace = true
  } else {
  // Default PROD config
  config = zap.NewProductionConfig()
+ config.DisableStacktrace = true
  }
 
  c.logger, err = config.Build(zap.AddCallerSkip(1))

docs/quick-start.md

@@ -20,7 +20,6 @@ The `Microbus` framework depends on a few third-party services:
 * Prometheus is an optional service that can be used to collect metrics from `Microbus` microservices
 * Grafana is an optional service that can visualize metrics collected by Prometheus
 * Jaeger is an optional service that can visualize distributed tracing spans
-* MariaDB is needed only for microservices that depend on it, such as the [directory example](./structure/examples-directory.md)
 
 Use `docker compose` from within the `setup` directory to install the above and set up the development environment.
 
@@ -34,7 +33,7 @@ docker compose -f microbus.yaml -p microbus up
 <img src="quick-start-1.png" width="1113">
 <p>
 
-The `-DV` (debug and verbose) flags of NATS slow it down considerably and are therefore disabled in `microbus.yaml`. To run with these flags enabled, it's recommended to run NATS in a separate terminal window instead of inside Docker.
+The `-DV` (debug and verbose) flags of NATS slow it down considerably and are therefore disabled in `microbus.yaml`. To run with these flags enabled, it's recommended to run NATS in a separate terminal window instead of inside Docker, and only for the duration these flags are needed.
 
 ## Run the Examples
 

docs/structure/examples-directory.md

@@ -4,7 +4,7 @@ The `directory.example` microservice is an example of a microservice that provid
 
 ## Adding SQL Support
 
-It only takes a few steps to add SQL support to a microservice.
+It takes a few steps to add SQL support to a microservice.
 
 Step 1: Edit `service.yaml` to define a configuration property to represent the connection string.
 
@@ -23,6 +23,8 @@ go generate
 Step 3: Define the database connection `db *sql.DB` as a member property of the `Service`, open it in `OnStartup` and close it in `OnShutdown`.
 
 ```go
+import _ "github.com/go-sql-driver/mysql"
+
 type Service struct {
  *intermediate.Intermediate // DO NOT REMOVE
 
@@ -34,6 +36,9 @@ func (svc *Service) OnStartup(ctx context.Context) (err error) {
  dsn := svc.SQL()
  if dsn != "" {
  svc.db, err = sql.Open("mysql", dsn)
+ if err == nil {
+ err = svc.db.PingContext(ctx)
+ }
  if err != nil {
  return errors.Trace(err)
  }
@@ -53,20 +58,19 @@ func (svc *Service) OnShutdown(ctx context.Context) (err error) {
 
 ## Connecting to the Database
 
-If you followed the [quick start guide](../quick-start.md), a MariaDB container should already be running in your Docker.
-If not, you can install and run it using:
+This example requires a MariaDB database instance. If you don't already have one installed, you can add it to Docker using:
 
 ```cmd
 docker pull mariadb
-docker run -p 3306:3306 --name mariadb1 -e MARIADB_ROOT_PASSWORD=secret1234 -d mariadb
+docker run -p 3306:3306 --name mariadb-1 -e MARIADB_ROOT_PASSWORD=secret1234 -d mariadb
 ```
 
 Next, create a database named `microbus_examples`.
 
 <img src="examples-directory-1.png" width="498">
 <p>
 
-From the `Exec` panel of the `microbus-mariadb-1` container, type:
+From the `Exec` panel of the `mariadb-1` container, type:
 
 ```cmd
 mysql -uroot -psecret1234
@@ -78,10 +82,10 @@ And then use the SQL command prompt to create the database:
 CREATE DATABASE microbus_examples;
 ```
 
-The connection string to the database is pulled from `examples/main/config.yaml` by the configurator and served to the `directory.example` microservice. Uncomment and adjust it if necessary to point to the location of your MariaDB database.
+The connection string to the database is pulled from `examples/main/config.yaml` by the configurator and served to the `directory.example` microservice. Adjust it as necessary to point to the location of your MariaDB database.
 
 ```yaml
-all:
+directory.example:
  SQL: "root:secret1234@tcp(127.0.0.1:3306)/microbus_examples"
 ```
 

docs/tech/errorcapture.md

@@ -97,16 +97,16 @@ With this in place, error messages look more like this, making it clear where th
 ```
 strconv.ParseInt: parsing "not-valid": invalid syntax
 
-calculator.(*Service).Square
- /src/github.com/microbus-io/fabric/examples/calculator/service.go:75
-connector.(*Connector).onRequest
- /src/github.com/microbus-io/fabric/connector/messaging.go:225
- calculator.example:443/square
-connector.(*Connector).Publish
- /src/github.com/microbus-io/fabric/connector/messaging.go:94
- http.ingress.sys -> calculator.example
-httpingress.(*Service).ServeHTTP
- /src/github.com/microbus-io/fabric/coreservices/httpingress/service.go:124
+- calculator.(*Service).Square
+ /src/github.com/microbus-io/fabric/examples/calculator/service.go:75
+- connector.(*Connector).onRequest
+ /src/github.com/microbus-io/fabric/connector/messaging.go:225
+ calculator.example:443/square
+- connector.(*Connector).Publish
+ /src/github.com/microbus-io/fabric/connector/messaging.go:94
+ http.ingress.sys -> calculator.example
+- httpingress.(*Service).ServeHTTP
+ /src/github.com/microbus-io/fabric/coreservices/httpingress/service.go:124
 ```
 
 ## Propagation Over the Wire

errors/trace.go

@@ -23,13 +23,14 @@ type trace struct {
 // String returns a string representation of the trace
 func (t *trace) String() string {
  var b strings.Builder
+ b.WriteString("- ")
  b.WriteString(t.Function)
- b.WriteString("\n\t")
+ b.WriteString("\n ")
  b.WriteString(t.File)
  b.WriteString(":")
  b.WriteString(strconv.Itoa(t.Line))
  for _, a := range t.Annotations {
- b.WriteString("\n\t")
+ b.WriteString("\n ")
  b.WriteString(a)
  }
  return b.String()