🥮 mooncakes.io

    agent-telemetry

    Download zip
    Version
    0.1.4
    License
    MulanPSL-2.0
    Repository
    Last updated
    4 months ago
    Downloads
    148

    #agent-telemetry

    OpenTelemetry instrumentation library for MoonBit Agent / LLM / Tool scenarios.

    It wraps the boilerplate OTel tracer / span / attribute code into business-semantic helpers, so agent developers only need to decide when to create spans and what business data to record.

    #Design Layers

    • Thin wrapper (lib.mbt): provider initialization, tracer cache, span lifecycle helpers such as start_span / end_span.
    • Semantic wrapper (genai.mbt, tool.mbt, agent.mbt): sets attributes according to the OpenTelemetry GenAI semantic conventions, covering chat, tool execution, and agent turn spans.

    #Quick Start

    moon add cybershang/agent-telemetry

    // Option 1: one-line initialization from environment variables.
    // Reads OTEL_SERVICE_NAME, OTEL_STDOUT, and OTEL_EXPORTER_OTLP_ENDPOINT.
    // Use ProcessUniqueRandom to avoid duplicate trace/span IDs across restarts.
    let providers = @telemetry.init_from_env(
      id_generator=@telemetry.ProcessUniqueRandom,
    )

    // Option 2: manually select an exporter.
    let config = @telemetry.TelemetryConfig::new(service_name="my-agent")
    let providers = @telemetry.init_telemetry(
      config,
      @telemetry.Otlp("http://localhost:4318"),
      id_generator=@telemetry.ProcessUniqueRandom,
    )

    // Metrics and logs need background tasks.
    @async.with_task_group((group) => {
      providers.spawn_background_tasks(group)

      // Create a GenAI chat span.
      let tracer = @telemetry.tracer("my-agent/llm")
      let meter = @telemetry.meter("my-agent/llm")
      let span = @telemetry.start_chat_span(
        tracer,
        provider_name="stepfun",
        model="step-3.7-flash",
        max_tokens=1024,
      )
      // ... send the request and obtain response_json ...
      @telemetry.record_llm_call(meter, "stepfun", "step-3.7-flash", success=true)
      @telemetry.record_chat_response(span, response_json)
      @telemetry.end_span_ok(span)

      providers.force_flush()
      providers.shutdown()
    })

    #Main API

    ScenarioFunctions
    GeneralTelemetryConfig::new, init_telemetry, init_from_env, TelemetryProviders, IdGeneratorOption, tracer, meter, logger, conversation_logger, start_span, end_span, end_span_ok, end_span_error, set_attributes, set_string_attribute, set_int_attribute, set_double_attribute, set_bool_attribute, set_json_attribute
    LLM chatstart_chat_span, record_chat_usage, record_chat_response, set_chat_http_error
    Toolstart_tool_span, record_tool_result, set_tool_error
    Agent turnstart_agent_turn_span, record_turn_metrics, set_turn_max_tool_turns_error
    Metricsrecord_llm_call, record_llm_latency, record_tool_call, record_turn_count
    Logsemit_log, log_info, log_warn, log_error, log_conversation_message

    #Custom Span Attributes

    The library already sets the standard GenAI semantic attributes for chat/tool/agent spans. When you need to record your own domain-specific metadata, use the typed attribute helpers:

    let span = @telemetry.start_span(tracer, "my.step")
    @telemetry.set_string_attribute(span, "app.user.id", "user-42")
    @telemetry.set_int_attribute(span, "app.retry.count", 3L)
    @telemetry.set_double_attribute(span, "app.score", 0.95)
    @telemetry.set_bool_attribute(span, "app.cached", true)
    @telemetry.set_json_attribute(span, "app.metadata", { "source": "api", "depth": 2 })
    @telemetry.end_span_ok(span)

    set_json_attribute serializes the Json value to a string, which is useful for structured metadata that does not fit the scalar attribute types. For arbitrary attribute lists you can still use set_attributes(span, attrs) with @otel.KeyValue values.

    #Instrumentation Guide

    See docs/instrumentation.md for a step-by-step guide that shows how to instrument LLM chat requests, tool executions, and agent turns using the agent-observability sample application as a reference.

    #Environment Variables

    init_from_env reads the following variables:

    VariableDescriptionDefault
    OTEL_SERVICE_NAMEService nameagent-telemetry
    OTEL_STDOUTUse the stdout exporter when set to truefalse
    OTEL_EXPORTER_OTLP_ENDPOINTOTLP/HTTP endpointhttp://localhost:4318
    OTEL_EXPORTER_OTLP_HEADERSGlobal OTLP headers, comma-separated key=value pairs(empty)
    OTEL_EXPORTER_OTLP_TRACES_HEADERSTrace-specific OTLP headers(empty, falls back to global)
    OTEL_EXPORTER_OTLP_METRICS_HEADERSMetric-specific OTLP headers(empty, falls back to global)
    OTEL_EXPORTER_OTLP_LOGS_HEADERSLog-specific OTLP headers(empty, falls back to global)
    GREPTIME_TRACE_PIPELINEGreptimeDB trace pipeline namegreptime_trace_v1
    GREPTIME_LOG_TABLETarget table for conversation logsgenai_conversations

    Signal-specific header variables take precedence over OTEL_EXPORTER_OTLP_HEADERS. This is useful for backends that require authentication tokens or custom routing headers.

    For example:

    OTEL_EXPORTER_OTLP_LOGS_HEADERS="Authorization=Bearer my-token, X-Scope-OrgID=tenant-1"

    #Log Routing

    The library maintains two separate loggers:

    • Default logger (logger / log_info / log_warn / log_error) writes to the standard OTLP logs table (opentelemetry_logs by default).
    • Conversation logger (conversation_logger / log_conversation_message) writes to the table configured by GREPTIME_LOG_TABLE (default genai_conversations).

    When exporting to GreptimeDB, this lets you keep general application logs and LLM conversation logs in separate tables.

    #Flushing and Shutting Down

    TelemetryProviders exposes force_flush() and shutdown() methods that flush/shutdown all three providers (traces, metrics, logs) and print any errors to stdout.

    providers.force_flush()
    providers.shutdown()

    Always call shutdown before the process exits so pending telemetry is exported.

    #ID Generator Option

    The id_generator parameter of init_telemetry / init_from_env supports:

    OptionDescription
    @telemetry.SdkDefaultUse the SDK default RandomIdGenerator
    @telemetry.ProcessUniqueRandomGenerate a process-unique seed from the current timestamp and a counter, avoiding duplicate trace/span IDs across restarts
    @telemetry.Custom(generator)Provide your own IdGenerator

    #Target Backend

    This library depends on opentelemetry/otlp, whose async/http and async/socket interfaces are native-only. Therefore moon.mod declares preferred_target = "native". Projects using this library should also run and test with --target native.

    #Example Project

    A complete agent example using this library can be found at:

    github.com/cybershang/moonbit-agent-observability

    #Testing

    moon test -p cybershang/agent-telemetry --target native

    #License

    Mulan PSL v2

    ExporterType

    source
    pub(all) enum ExporterType {
      Stdout
      Otlp(String)
      Custom(
    SpanExporter    )
      NoOp
    }

    Exporter type for telemetry initialization.

    IdGeneratorOption

    source
    pub(all) enum IdGeneratorOption {
      SdkDefault
      ProcessUniqueRandom
      Custom(
    IdGenerator    )
    }

    ID generator option for telemetry initialization.

    TelemetryConfig

    source
    pub struct TelemetryConfig {
      service_name : String
    } derive(
    Debug    )

    Configuration for initializing OpenTelemetry in an agent application.

    TelemetryConfig::new

    source
    fn TelemetryConfig::new(service_name? : String) -> TelemetryConfig

    Create a new telemetry configuration.

    TelemetryProviders

    source

    Holder for all initialized OpenTelemetry SDK providers.

    TelemetryProviders::force_flush

    source
    async fn TelemetryProviders::force_flush(self : TelemetryProviders) -> Unit

    Flush all providers and print any errors.

    TelemetryProviders::shutdown

    source
    async fn TelemetryProviders::shutdown(self : TelemetryProviders) -> Unit

    Shut down all providers and print any errors.

    TelemetryProviders::spawn_background_tasks

    source
    fn TelemetryProviders::spawn_background_tasks(self : TelemetryProviders, group : 
    TaskGroup    [Unit], allow_failure? : Bool) -> Unit

    Spawn background tasks required by metrics (periodic reader) and logs (batch processor).

    conversation_logger

    source
    fn conversation_logger(scope_name : String) -> 
    Logger

    Get or create a logger for conversation messages. Logs from this logger go to the configured GenAI conversations table (default genai_conversations).

    emit_log

    source

    Emit a structured log record.

    end_span

    source

    End a span, optionally setting a final status.

    end_span_error

    source
    async fn end_span_error(span : 
    Span    , description~ : String) -> Unit

    End a span marking it as failed.

    end_span_ok

    source

    End a span marking it as successful.

    init_from_env

    source
    async fn init_from_env(service_name? : String, id_generator? : IdGeneratorOption) -> TelemetryProviders

    Initialize the global providers from standard environment variables.

    Reads:
    • OTEL_SERVICE_NAME (overrides service_name)
    • OTEL_STDOUT (true selects the stdout exporter)
    • OTEL_EXPORTER_OTLP_ENDPOINT (when OTEL_STDOUT is not true)

    init_telemetry

    source
    async fn init_telemetry(config : TelemetryConfig, exporter_type : ExporterType, id_generator? : IdGeneratorOption) -> TelemetryProviders

    Initialize the global OpenTelemetry providers (traces, metrics, logs).

    log_conversation_message

    source
    async fn log_conversation_message(scope_name : String, role : String, content : String, index? : Int, trace_context? : 
    SpanContext    ?) -> Unit

    Emit a conversation message log compatible with the genai-observability GreptimeDB dashboard SQL.

    Body JSON shape:
    • user / tool: {"content":"..."}
    • assistant: {"index":0,"message":{"role":"assistant","content":"..."}}

    log_error

    source
    async fn log_error(scope_name : String, body : String, attributes? : Array[
    KeyValue    ], trace_context? : 
    SpanContext    ?) -> Unit

    Emit an error log.

    log_info

    source
    async fn log_info(scope_name : String, body : String, attributes? : Array[
    KeyValue    ], trace_context? : 
    SpanContext    ?) -> Unit

    Emit an info log.

    log_warn

    source
    async fn log_warn(scope_name : String, body : String, attributes? : Array[
    KeyValue    ], trace_context? : 
    SpanContext    ?) -> Unit

    Emit a warning log.

    logger

    source

    Get or create a logger for the given scope name. Logs from this logger go to the default opentelemetry_logs table.

    make_random_id_generator

    source

    Create an IdGenerator with a process-unique seed.

    This helper works around the SDK default RandomIdGenerator's fixed ChaCha8 seed, which produces duplicate trace/span IDs across process restarts.

    meter

    source

    Get or create a meter for the given scope name.

    now_seconds

    source
    async fn now_seconds() -> Double

    Current wall-clock time in seconds since the Unix epoch.

    record_chat_response

    source
    fn record_chat_response(span : 
    Span    , response_json : Json, output_messages? : Json?) -> Unit

    Record response metadata and optional output messages for a successful chat request.

    Extracts gen_ai.response.id, gen_ai.response.model and gen_ai.response.finish_reasons from response_json. Sets gen_ai.output.messages when output_messages is provided.

    record_chat_usage

    source
    fn record_chat_usage(span : 
    Span    , usage_json : Json) -> Unit

    Record usage attributes from a GenAI response usage object.

    Sets gen_ai.usage.input_tokens and gen_ai.usage.output_tokens when present.

    record_llm_latency

    source
    fn record_llm_latency(meter : 
    Meter    , provider_name : String, model : String, seconds~ : Double) -> Unit

    Record the duration of one GenAI chat operation in seconds.

    record_llm_token_usage

    source
    fn record_llm_token_usage(meter : 
    Meter    , provider_name : String, model : String, token_type : String, value : Int64) -> Unit

    Record token usage for one GenAI chat operation.

    record_tool_call

    source
    fn record_tool_call(meter : 
    Meter    , tool_name : String, success~ : Bool) -> Unit

    Record one tool execution.

    record_tool_result

    source
    fn record_tool_result(span : 
    Span    , result : String) -> Unit

    Record the result of a tool execution and mark the span as successful.

    record_turn_count

    source
    fn record_turn_count(meter : 
    Meter    , max_tool_turns_reached~ : Bool) -> Unit

    Record one completed agent turn.

    record_turn_metrics

    source
    fn record_turn_metrics(span : 
    Span    , actual_turns : Int, tool_call_count : Int, output : String) -> Unit

    Record turn-level metrics before ending an agent turn span.

    Sets:
    • agent.turn.actual_turns
    • agent.turn.tool_call_count
    • agent.turn.output

    set_attributes

    source

    Set multiple attributes on a span.

    set_bool_attribute

    source
    fn set_bool_attribute(span : 
    Span    , name : String, value : Bool) -> Unit

    Set a boolean attribute on a span.

    set_chat_http_error

    source
    fn set_chat_http_error(span : 
    Span    , status_code : Int, message? : String) -> Unit

    Mark a chat span as failed due to an HTTP error.

    Sets error.type to the status code string, records the span status as error, and emits an llm.http_error event.

    set_double_attribute

    source
    fn set_double_attribute(span : 
    Span    , name : String, value : Double) -> Unit

    Set a floating-point attribute on a span.

    set_int_attribute

    source
    fn set_int_attribute(span : 
    Span    , name : String, value : Int64) -> Unit

    Set an integer attribute on a span.

    set_json_attribute

    source
    fn set_json_attribute(span : 
    Span    , name : String, value : Json) -> Unit

    Set a JSON attribute on a span. The JSON value is serialized to a string, which is useful for structured custom metadata that does not have a dedicated scalar attribute.

    set_string_attribute

    source
    fn set_string_attribute(span : 
    Span    , name : String, value : String) -> Unit

    Set a string attribute on a span.

    set_tool_error

    source
    fn set_tool_error(span : 
    Span    , description : String) -> Unit

    Mark a tool span as failed with a description.

    set_turn_max_tool_turns_error

    source
    fn set_turn_max_tool_turns_error(span : 
    Span    ) -> Unit

    Mark an agent turn span as failed due to reaching the maximum tool turns.

    start_agent_turn_span

    source

    Start a span for a single agent turn.

    Sets:
    • agent.turn.input
    • agent.turn.max_tool_turns

    start_chat_span

    source
    fn start_chat_span(tracer : 
    Tracer    , provider_name : String, model : String, max_tokens : Int, input_messages? : Json?, server_address? : String?, server_port? : Int?, parent_context? : 
    Context    ) -> 
    Span

    Start a span for a GenAI chat request following OpenTelemetry GenAI conventions.

    Sets:
    • gen_ai.operation.name = "chat"
    • gen_ai.provider.name
    • gen_ai.request.model
    • gen_ai.request.max_tokens
    • gen_ai.input.messages when input_messages is provided
    • server.address and server.port when provided

    start_span

    source

    Start a new span with the given tracer.

    start_tool_span

    source

    Start a span for a GenAI tool execution.

    Sets:
    • gen_ai.tool.name
    • gen_ai.tool.call.arguments

    tracer

    source
    fn tracer(scope_name : String, version? : String) -> 
    Tracer

    Get or create a tracer for the given scope name.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsBuild queueStatistics

    © 2026 mooncakes.io