Environment Variables

The Microbus framework uses environment variables for various purposes:

  • Initializing the connection to NATS
  • Identifying the deployment environment (PROD, LAB, LOCAL, TESTING)
  • Designating a plane of communication
  • Enabling output of debug-level messages
  • Configuring the URL to the OpenTelemetry collector endpoint
  • Designating a geographic locality

Environment variables may also be set by placing an env.yaml or env.local.yaml file in the working directory of the executable running the microservice, or any ancestor directory thereof. The bundled example application includes such a file at main/env.yaml. The env package writes these values through to the real OS environment at process start, so third-party SDKs that read os.Getenv directly (the OTel exporter, gRPC, AWS SDK, etc.) see them transparently. Real OS env vars set before the binary launches always win over yaml values.

Transports

A microservice can’t communicate with other microservices, including the configurator microservice, before connecting to the transport. Initializing the NATS connection relies on MICROBUS_NATS for the server URL; authentication is configured via per-service .creds files in CWD.

MICROBUS_SHORT_CIRCUIT can be set to 0 or false to disable the short-circuit transport. It is generally recommended to keep the short-circuit transport enabled.

Startup and Shutdown Budgets

MICROBUS_STARTUP_TIME_BUDGET and MICROBUS_SHUTDOWN_TIME_BUDGET set the time application.Run allots to bringing the application up and down. Both accept Go duration strings (30s, 2m, 90s).

The defaults are 120s for startup and 24s for shutdown. The shutdown default sits below Kubernetes’ default terminationGracePeriodSeconds of 30s, leaving the orchestrator a few seconds to finalize before SIGKILL. Kubernetes has no comparable hard ceiling on startup (startup probes and progressDeadlineSeconds are operator-tuned and typically much longer), so the 120s default gives microservices headroom to warm caches, load ML models, or wait on slow dependencies. The chosen budget is applied as the deadline on the ctx passed to each microservice’s OnStartup / OnShutdown, and Shutdown partitions the remaining budget across its drain phases.

Unparseable values are silently treated as unset rather than reducing the budget to zero. For programmatic control bypass Run and call Application.Startup / Application.Shutdown with your own context.

Deployment

The MICROBUS_DEPLOYMENT environment variable determines the deployment environment of the microservice: PROD, LAB, LOCAL or TESTING. If not specified, PROD is assumed, unless connecting to nats://localhost:4222 or nats://127.0.0.1:4222 in which case LOCAL is assumed.

Plane of Communication

The plane of communication is a unique prefix set for all communications sent or received over NATS. It is used to isolate communication among a group of microservices over a NATS cluster that is shared with other microservices.

If not explicitly set via the SetPlane method of the Connector, the value is pulled from the MICROBUS_PLANE environment variable. The plane must include only alphanumeric characters and is case-sensitive.

Applications created with application.NewTesting set a random plane to eliminate the chance of collision when tests are executed in parallel in the same NATS cluster, e.g. using go test ./... -p=8.

In most cases there is no need to customize the plane of communications.

Locality

The MICROBUS_LOCALITY environment variable sets the locality of the microservice, which is used as the basis for locality-aware routing.

Logging

Setting the MICROBUS_LOG_DEBUG environment variable to 1 or true is required for microservices to log debug-level messages.

OpenTelemetry

Microbus pushes telemetry to Grafana via its OpenTelemetry collector across three signals - traces, metrics and logs. The endpoint of the collector is configured per-signal using OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT and OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, or for all three at once using the generic OTEL_EXPORTER_OTLP_ENDPOINT. A per-signal endpoint overrides the generic one for that signal. All exporters in one executable that target the same endpoint over the same protocol share a single connection to the collector.

The OTEL_METRIC_EXPORT_INTERVAL variable can be used to set the interval (in milliseconds) between pushes of metrics. It defaults to 15 seconds in LOCAL or TESTING deployments, and 60 seconds in PROD or LAB deployments.

The OTEL_EXPORTER_OTLP_TIMEOUT variable sets the per-export timeout in milliseconds. Microbus uses lazy connection (no eager dial at startup) and disables retries on the OTLP exporter, so a misconfigured or unreachable collector does not stall startup or block exports indefinitely - exports simply time out and are dropped.

Transport security follows the endpoint URL scheme (https is secured) unless OTEL_EXPORTER_OTLP_INSECURE (or its per-signal form, e.g. OTEL_EXPORTER_OTLP_LOGS_INSECURE) overrides it. A custom CA bundle for the collector is supplied via OTEL_EXPORTER_OTLP_CERTIFICATE, and a client certificate for mTLS via OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE and OTEL_EXPORTER_OTLP_CLIENT_KEY; each also has a per-signal form.

Other OpenTelemetry environment variables are respected.

Set the MICROBUS_PROMETHEUS_EXPORTER variable to 1 or true to enable Prometheus metric collection in the microservice. This enables the metrics core microservice to collect and aggregate metrics from the microservice.

Backward Deployments NATS Connection Settings Forward