moontel

fn traced_request(rand : (Int32) -> Bytes, at : Int64) -> @trace.Span raise {
  let tracer = @trace.Tracer::new(
    rand~,
    sink=@trace.Recorder::new(),
    sampler=@trace.parent_based(root=@trace.always),
  )
  let span = tracer.start("GET /orders/{id}", kind=@trace.Server, at~)
  span.set_attribute("http.response.status_code", @trace.Int(200L))
  span.finish(at=at + 1_000_000L)
  span
}

#Install

moon add moonbitstack/moontel

#Annotations

#tel.span("orders.place", kind=server, attr="item")
fn place(item : String) -> Int raise Sold {
  ...
}

let receipt = place_traced(tracer, "tea", now=clock)
let nested = place_traced(tracer, "tea", now=clock, parent=span.context())

rule(name: "span", command: "moonx moonbitstack/moontel/cmd/span -C \"$mod_dir\" \"$input\" -o \"$output\"")

dev_build(rule: "span", input: "orders.mbt", output: "orders.g.mbt")
formatter(ignore: [ "orders.g.mbt" ])

#The seams

struct Printer {}

impl @trace.Sink for Printer with fn accept(self, span) {
  ignore(self)
  println("\{span.name} took \{span.duration()} ns")
}

fn traced_with_printer(rand : (Int32) -> Bytes, at : Int64) -> Unit raise {
  let tracer = @trace.Tracer::new(rand~, sink=Printer::{}, sampler=@trace.always)
  let span = tracer.start("GET /orders/{id}", at~)
  span.finish(at=at + 1L)
}

#Sampling

struct Everything {}

impl @trace.Sampler for Everything with fn should_sample(_, _) {
  @trace.RecordAndSample
}

impl @trace.Sampler for Everything with fn description(_) {
  "Everything"
}

#Carrying a trace between services

fn trace_on_request(headers : Array[(String, String)]) -> @trace.TraceContext? {
  @propagate.extract(headers).context
}

fn inbound_headers() -> Array[(String, String)] {
  [
    ("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"),
    ("tracestate", "vendor=abc"),
    ("baggage", "userId=alice"),
  ]
}

fn forward(
  headers : Array[(String, String)],
  span : @trace.Span,
  baggage : @propagate.Baggage,
) -> Array[(String, String)] {
  @propagate.inject(headers, { context: Some(span.context()), baggage })
}

#ASGI

fn layer(tracer : @trace.Tracer, now : () -> Int64) -> @asgi.Tracing {
  @asgi.Tracing::new(tracer~, now~)
}

#Sending the signals

fn traced(now : () -> Int64, rand : (Int32) -> Bytes) -> @trace.Tracer {
  let transport = @http.HttpTransport::new()
  let exporter = @otlp.TraceExporter::new(
    transport~,
    endpoint="http://localhost:4318",
    resource=@otlp.Resource::of_service("orders"),
    now~,
    rand~,
  )
  @trace.Tracer::new(rand~, sink=exporter, sampler=@trace.parent_based(root=@trace.always))
}

fn traced_binary(now : () -> Int64, rand : (Int32) -> Bytes) -> @trace.Tracer {
  let transport = @http.HttpTransport::new()
  let exporter = @otlp.TraceExporter::new(
    transport~,
    endpoint="http://localhost:4318",
    encoding=@binary.protobuf,
    now~,
    rand~,
  )
  @trace.Tracer::new(rand~, sink=exporter, sampler=@trace.parent_based(root=@trace.always))
}

async fn over_grpc(now : () -> Int64, rand : (Int32) -> Bytes) -> @otlp.TraceExporter {
  let channel = @grpc.GrpcTransport::connect(host="localhost")
  @otlp.TraceExporter::new(
    transport=channel,
    endpoint="http://localhost:4317",
    encoding=@binary.protobuf,
    now~,
    rand~,
  )
}

#Logs

fn failing(logs : &@log.Sink, span : @trace.Span, now : () -> Int64) -> Unit {
  let logger = @log.Logger::new(sink=logs, now~, scope="orders/payments").inside(span)
  logger.info("order placed", attributes=[("order.id", @trace.Int(42L))])
  logger.warn("the card was retried once")
}

#Metrics

fn record_latency(
  provider : @meter.MeterProvider,
  seconds : Double,
  attributes : @meter.Attributes,
) -> Unit raise {
  let meter = provider.meter(name="checkout")
  let duration = meter.histogram(
    "gen_ai.client.operation.duration",
    description="GenAI operation duration.",
    unit="s",
  )
  duration.record(seconds, attributes~, at=0L)
}

fn collect(provider : @meter.MeterProvider) -> Array[@otlp.Metric] {
  provider.collect(at=1_000_000L)
}

#Reported at collection

fn queue_depth(provider : @meter.MeterProvider) -> Unit raise {
  let meter = provider.meter(name="checkout")
  let queue = meter.observable_gauge(
    "checkout.queue.depth",
    description="Requests waiting.",
    unit="{request}",
    observe=fn(observer) { observer.observe(7.0) },
  )
  ignore(queue)
}

#Buckets that follow the measurements

fn exponential_latency(provider : @meter.MeterProvider) -> Unit raise {
  let meter = provider.meter(name="checkout")
  let latency = meter.exponential_histogram(
    "checkout.latency",
    description="Time a request took.",
    unit="s",
  )
  latency.record(0.004, at=0L)
  latency.record(0.052, at=0L)
  latency.record(1.7, at=0L)
}

#Views

fn viewed_provider() -> @meter.MeterProvider {
  @meter.MeterProvider::new(
    sink=@otlp.MetricRecorder::new(),
    now=() => 0L,
    views=[
      @meter.View::new(
        instrument="checkout.token.usage",
        name="checkout.tokens",
        attribute_keys=["gen_ai.provider.name"],
      ),
      @meter.View::new(instrument="checkout.debug.tick", aggregation=@meter.Drop),
    ],
  )
}

#Exemplars

fn with_current_span(span : @trace.TraceContext) -> @meter.MeterProvider {
  @meter.MeterProvider::new(
    sink=@otlp.MetricRecorder::new(),
    now=() => 0L,
    current=() => Some(span),
  )
}

fn chat_attributes() -> @meter.Attributes {
  @meter.gen_ai_client_attributes(
    provider="openai",
    operation="chat",
    request_model="gpt-5",
  )
}

fn export(
  metrics : @otlp.MetricsExporter,
  now : () -> Int64,
  elapsed : Double,
) -> Unit raise {
  let registry = @metric.Registry::new()
  let latency = registry.histogram("order_latency", "Latency.", unit="seconds")
  latency.observe(elapsed)
  for metric in @p8s.bridge(registry.collect(at=0.0), at=now()) {
    metrics.record(metric)
  }
}

#The GenAI names

#The interface

#trace — spans, samplers, the sink seam

#propagate — the W3C headers

#asgi — the middleware

#log — records, the logger, the sinks

#meter — the instruments, the views and the exemplars

#otlp — the export

#otlp/http, otlp/p8s, semconv

#Limits

#Conformance

• W3C Trace Context. The official suite in integration/trace-context drives a hop built on this library, and every case passes.
• OTLP. otel/opentelemetry-collector-contrib 0.164.0 decodes spans, log records and metrics on HTTP/JSON, HTTP/JSON with gzip, HTTP/protobuf and gRPC. The CI job reads the collector's log and counts each item on each transport.
• Metrics. weaver registry live-check runs against two registries. Against integration/weaver/registry, which describes the seven metrics of src/examples/06-meter, it reports seven metrics, seven data points, registry coverage 1.0 and no advisory. Against the GenAI semantic conventions pinned at aa3b7f4 it recognises gen_ai.client.operation.duration and the four GenAI attributes. Seven violations remain, and they are known: the six demonstration names (gen_ai.client.token.usage, gen_ai.client.active.requests, gen_ai.client.queue.length, gen_ai.client.tokens.reported, gen_ai.client.workers.reported, moontel.example.latency) are not in that registry, and service.name is a resource attribute it does not define. The remaining improvements are stability levels — every GenAI metric and attribute is still development upstream — and the optional server.address, server.port and conditional error.type attributes.

#What this is not

• No storage, no query, no page. A collector or a hosted backend reads what this sends.
• No clock, no sockets, no framework. A tracer is handed its times, its ids and its destination; a meter is handed its clock; a transport is handed a request.

#Examples

moon run src/examples/00-hello        # a root span, a child, attributes and an event
moon run src/examples/01-propagate    # reading a request's context, writing the next one's
moon run src/examples/02-asgi         # the middleware over an application
moon run src/examples/03-annotated    # the annotation, and the wrapper it generates
moon run src/examples/04-otlp         # three signals, to a collector
moon run src/examples/05-grpc         # the same three signals, over gRPC
moon run src/examples/06-meter        # observed instruments, views and an exponential histogram

#Licence