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))
}

let channel = @grpc.GrpcTransport::connect(host="localhost")
let traces = @otlp.TraceExporter::new(
  transport=channel,
  endpoint="http://localhost:4317",
  format=@otlp.BodyFormat::Protobuf,
  now=millis,
  rand=random_bytes,
)

#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 export(metrics : @otlp.MetricsExporter, now : () -> Int64) -> 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

#otlp — the export

#otlp/http, otlp/p8s, semconv

#Limits

#What this is not

• No protobuf and no gRPC. OTLP over HTTP carries JSON here.
• No meter. Metrics are read out of a snapshot a program already keeps and translated to OTLP; nothing is counted twice.
• 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 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/04-otlp         # three signals, to a collector

#Licence