#OpenTelemetry for MoonBit

• public API packages for traces, metrics, logs, context, baggage, and propagation
• SDK packages for providers, processors, readers, samplers, resources, and in-memory test exporters
• print exporters for local learning and debugging
• OTLP HTTP exporters for production-oriented export through the OpenTelemetry Protocol
• semantic-convention constants and generated OTLP protocol model types

#Mental Model

• API layer: what libraries should depend on. It provides stable instrumentation types such as Tracer, Meter, Logger, Context, and KeyValue. If an application does not install an SDK provider, the API layer is no-op by default.
• SDK layer: what applications configure. It owns resources, samplers, processors, readers, exporters, batching, flushing, and shutdown.

#Package Guide

#Quick Start: Trace To Stdout

///|
async fn _readme_trace_to_stdout() -> Unit {
  let exporter = @print.SpanExporter::new()
  let provider = @sdk.tracer_provider_builder()
    .with_simple_exporter(exporter.into_span_exporter())
    .build()

  @sdk.set_tracer_provider(provider)

  let tracer = tracer("checkout-service", version=Some("1.0.0"))
  let span = tracer.start("charge-card")
  span.set_attribute(KeyValue::new("payment.system", String("test")))
  span.set_status(@trace.Status::ok())
  span.end()

  ignore(provider.shutdown())
}

#Instrumenting Libraries

///|
pub async fn _library_operation() -> Unit {
  let tracer = tracer(
    "moonbit-community/example-library",
    version=Some("0.1.0"),
  )
  let span = tracer.start("example.operation")
  span.set_attribute(KeyValue::new("example.kind", String("demo")))
  // Library work goes here.
  span.end()
}

#Application Setup

1. Build a trace, log, or metric provider in sdk/*.
2. Register SDK providers with sdk.set_*_provider() if code uses the root moonbit-community/opentelemetry package. These helpers also update interface/global with API-layer providers.
3. Spawn background tasks when using batch span/log processors or periodic metric readers.
4. Flush and shut down providers during application teardown.

///|
async fn _spawn_background_tasks_shape() -> Unit {
  @async.with_task_group(group => @sdk.spawn_background_tasks(group))
}

#Metrics

• Counter: monotonic value that only increases, such as requests served or bytes sent
• UpDownCounter: value that can increase or decrease, such as active sessions or queue depth
• Histogram: distribution of measurements, such as latency or payload size
• Gauge: latest value for state that can move up or down, such as temperature or memory usage
• observable instruments: callbacks for values already owned by another system

///|
fn _record_request_metrics() -> Unit {
  let meter = meter("checkout-service")
  let request_count = meter.u64_counter("http.server.request.count").build()
  let request_latency = meter
    .f64_histogram("http.server.duration")
    .with_unit("ms")
    .build()

  request_count.add(1UL, attributes=[
    KeyValue::new("http.request.method", String("POST")),
  ])
  request_latency.record(32.5, attributes=[
    KeyValue::new("http.route", String("/checkout")),
  ])
}

#Logs

///|
async fn _emit_structured_log() -> Unit {
  let logger = logger("checkout-service")
  if logger.event_enabled(Info, "checkout") {
    let record = logger.create_log_record()
    record.set_event_name("checkout.completed")
    record.set_target("checkout")
    record.set_severity_number(Info)
    record.set_body(String("checkout completed"))
    record.add_attribute("cart.items", Int(3L))
    logger.emit(record)
  }
}

#Propagation

///|
fn _inject_headers(context : Context) -> Map[String, String] {
  let headers = {}
  get_text_map_propagator(propagator => {
    propagator.inject_context(context, headers)
  })
  headers
}

#OTLP Export

docker run --rm -p 4318:4318 otel/opentelemetry-collector:latest

#Environment Variables

#Practical Guidance

• Use instrumentation names that identify the library or component, for example moonbit-community/http-client.
• Prefer semantic-convention constants from semantics/* instead of hard-coded keys when a standard key exists.
• Add low-cardinality attributes by default. Avoid user IDs, raw URLs, or unbounded strings as metric attributes.
• Create metric instruments once and reuse them.
• Always call shutdown() on providers you own so buffered telemetry is flushed.
• Library code should not import sdk or exporters unless it is explicitly an integration package.

///|
fn _semantic_convention_attribute() -> Array[KeyValue] {
  [KeyValue::new(@semtrace.HTTP_REQUEST_METHOD, String("GET"))]
}

#Read Next

• interface/trace/README.mbt.md: spans, parent context, events, links, status, and no-op trace behavior
• interface/metrics/README.mbt.md: choosing instruments and recording measurements
• interface/logs/README.mbt.md: structured log records and log bridge behavior
• interface/propagation/README.mbt.md: W3C trace context and baggage propagation
• sdk/README.mbt.md: provider configuration, processors, readers, environment variables, and lifecycle
• otlp/README.mbt.md: OTLP exporter behavior
• print/README.mbt.md: stdout exporter behavior

#Integration Tests