Enabling OpenTelemetry for a MoonBit Agent
The golem-otlp-exporter is a built-in plugin that exports agent telemetry (traces, logs, metrics) to any OTLP-compatible collector via OTLP/HTTP. No plugin installation is needed — just enable it in the application manifest.
Step 1 — Enable the Plugin in golem.yaml
Add the plugin to the component (or agent) that should emit telemetry:
components:
my-app:service:
plugins:
- name: golem-otlp-exporter
version: "1.5.8"
parameters:
endpoint: "http://localhost:4318"
signals: "traces,logs,metrics"
Plugin Parameters
| Parameter | Required | Description |
|---|---|---|
endpoint |
Yes | OTLP collector base URL (e.g., http://localhost:4318) |
signals |
No | Comma-separated: traces, logs, metrics. Default: traces |
headers |
No | Comma-separated key=value HTTP headers (e.g., x-api-key=secret) |
service-name-mode |
No | agent-id (default) or agent-type |
Step 2 — Deploy
golem deploy --yes
After deployment, newly created agents from this component automatically send telemetry to the configured collector.
What Gets Exported
Traces
Spans are created automatically for:
- Agent invocations
- RPC calls to other agents
- Outgoing HTTP requests
Trace and span IDs propagate from inbound HTTP requests (via code-first routes) and are included in outgoing HTTP request headers automatically.
Custom Spans
Add "golemcloud/golem_sdk/context" @context and
"golemcloud/golem_sdk/logging" @log to the imports in moon.pkg.
Use the @context module for automatic span lifecycle management:
@context.with_span(
"my-operation",
attributes=[("env", "production"), ("service", "my-service"), ("version", "1.0")],
fn(span) {
// ... do work ...
// Add more attributes dynamically if needed:
span.set_attribute("step", "processing")
let ctx = @context.current_context()
println("trace_id: " + ctx.trace_id())
},
)
with_span automatically finishes the span when the callback returns.
Logs
When logs is included in signals, all log output is forwarded to the OTLP collector. See the golem-logging-moonbit skill for full logging guidance.
println("Hello from MoonBit!")
@log.debug("This is a debug log entry")
Metrics
When metrics is included in signals, exported metrics include the following (this is not an exhaustive list):
| Metric | Type | Description |
|---|---|---|
golem.invocation.count |
Counter | Number of agent method invocations |
golem.invocation.duration_ns |
Counter | Invocation duration |
golem.invocation.fuel_consumed |
Counter | Fuel consumed by invocations |
golem.invocation.pending_count |
Counter | Number of queued invocation requests, not current queue depth |
golem.host_call.count |
Counter | Number of internal host calls |
golem.log.count |
Counter | Number of log entries emitted |
golem.memory.initial_bytes |
Gauge | Initially allocated memory |
golem.memory.total_bytes |
Gauge | Total allocated memory |
golem.memory.growth_bytes |
Counter | Memory growth since start |
golem.component.size_bytes |
Gauge | Component size in bytes |
golem.error.count |
Counter | Number of recorded errors |
golem.interruption.count |
Counter | Number of interrupt requests |
golem.exit.count |
Counter | Number of process exit signals |
golem.restart.count |
Counter | Number of times a fresh state was created |
golem.resources.created |
Counter | Number of internal resources created |
golem.resources.dropped |
Counter | Number of internal resources dropped |
golem.resources.active |
Gauge | Number of active internal resources |
golem.update.success_count |
Counter | Number of successful updates |
golem.update.failure_count |
Counter | Number of failed updates |
golem.transaction.committed |
Counter | Number of committed remote transactions |
golem.transaction.rolled_back |
Counter | Number of rolled back remote transactions |
golem.snapshot.size_bytes |
Counter | Snapshot size in bytes |
golem.oplog_processor.lag |
Gauge | Oplog processor delivery lag |
These are emitted OTLP names. A backend such as Prometheus may normalize dots to underscores and add suffixes; use that backend's mapping when writing queries.
Each metric includes service.name, golem.agent.id, golem.component.id, and golem.component.version attributes.
Export Semantics
- Long-lived spans retain their origin trace across invocations. Failed or retrying attempts do not close the logical span. Logs use their recorded trace context.
- Streams export aggregate item counts, not a span per item. Query active-resource counts and initial/total memory as gauges.
- Use
agent-typeservice-name mode to exclude constructor parameters and phantom IDs fromservice.name.golem.agent.idstill contains the full identity. - Treat collector export as best effort, not exactly-once delivery. A failed send can lose telemetry; traces, logs, and metrics are attempted independently.
- Fork/revert cannot retract exported telemetry. Agent deletion does not close open spans, and switching plugin instances can lose open-span state.
Local Observability Stack
The Golem repository includes a ready-made Docker Compose setup at docker-examples/otlp-collector/:
docker compose -f docker-examples/otlp-collector/docker-compose.yml up -d
This starts:
- OTel Collector on port 4318 (OTLP/HTTP)
- Jaeger on http://localhost:16686 (traces)
- Prometheus on http://localhost:9090 (metrics)
- Loki via Grafana (logs)
- Grafana on http://localhost:3000 (admin/admin)
Configure the plugin with endpoint: "http://localhost:4318" to use this stack.
Per-Environment Configuration
Use presets to vary the endpoint across environments:
components:
my-app:service:
plugins:
- name: golem-otlp-exporter
version: "1.5.8"
parameters:
endpoint: "http://localhost:4318"
signals: "traces,logs,metrics"
presets:
app-env:production:
pluginsMergeMode: replace
plugins:
- name: golem-otlp-exporter
version: "1.5.8"
parameters:
endpoint: "https://otel.prod.example.com:4318"
headers: "x-api-key={{ OTLP_API_KEY }}"
signals: "traces,logs,metrics"
Key Points
- Built-in — no
golem plugin registerneeded, just add togolem.yaml - Deploy required — run
golem deployafter adding the plugin configuration - Trace context propagates automatically through HTTP routes and RPC calls
- Use
@context.with_spanfor custom spans with automatic lifecycle management - Plugin can be activated/deactivated per agent with
golem agent activate-plugin/golem agent deactivate-plugin
Related Skills
- Load
golem-manage-pluginsfor the general plugin installation model (manifest sections, CLI commands, priority, per-environment configuration)