🥮 mooncakes.io
    Sign in

    agent-telemetry

    Download zip
    Version
    0.1.6
    License
    MulanPSL-2.0
    Repository
    Last updated
    3 months ago
    Downloads
    93

    Dependencies

    #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,
        "stepfun",
        "step-3.7-flash",
        1024,
        temperature=Some(0.7),
        stream=Some(true),
      )
      // ... send the request and obtain response_json ...
      @telemetry.set_usage(span, 100L, 25L, cache_read_input_tokens=50L)
      @telemetry.set_response(span, response_json, output_messages~)
      @telemetry.end_span(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, set_attributes, set_string, set_int, set_double, set_bool, set_json
    LLM chatstart_chat_span, set_usage, set_response, set_http_error
    Toolstart_tool_span, set_tool_result, set_tool_error
    Agent turnstart_agent_turn_span, set_turn, set_turn_exhausted
    Agent invocationstart_invoke_agent_span
    Planstart_plan_span
    Metricsrecord_llm_latency, record_usage, record_tool_call, record_turn, record_agent_duration, record_tool_duration
    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(span, "app.user.id", "user-42")
    @telemetry.set_int(span, "app.retry.count", 3L)
    @telemetry.set_double(span, "app.score", 0.95)
    @telemetry.set_bool(span, "app.cached", true)
    @telemetry.set_json(span, "app.metadata", { "source": "api", "depth": 2 })
    @telemetry.end_span(span)

    set_json 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.

    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_agent_duration

    source
    fn record_agent_duration(meter : 
    Meter    , agent_name : String, seconds~ : Double) -> Unit

    Record the duration of one GenAI agent invocation in seconds.

    Metric: gen_ai.invoke_agent.duration (Histogram, unit="s")

    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_tool_call

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

    Record one tool execution.

    record_tool_duration

    source
    fn record_tool_duration(meter : 
    Meter    , tool_name : String, seconds~ : Double) -> Unit

    Record the duration of one GenAI tool execution in seconds.

    Metric: gen_ai.execute_tool.duration (Histogram, unit="s")

    record_turn

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

    Record one completed agent turn.

    record_usage

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

    Record token usage for one GenAI chat operation.

    set_attributes

    source

    Set multiple attributes on a span.

    set_bool

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

    Set a boolean on a span.

    set_double

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

    Set a floating-point on a span.

    set_http_error

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

    Mark a chat span as failed due to an error.

    Sets error.type, records the span status as error, and emits a gen_ai.client.operation.exception event following the OTel GenAI semantic conventions.

    set_int

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

    Set an integer on a span.

    set_json

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

    Set a JSON 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_response

    source
    fn set_response(span : 
    Span    , response_json : Json, output_messages? : Json?, time_to_first_chunk? : Double?) -> Unit

    Set response attributes for a successful chat request.

    Extracts gen_ai.response.id, gen_ai.response.model and gen_ai.response.finish_reasons from response_json. Also sets gen_ai.output.messages and gen_ai.response.time_to_first_chunk when provided.

    set_string

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

    Set a string 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_tool_result

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

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

    set_turn

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

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

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

    set_turn_exhausted

    source
    fn set_turn_exhausted(span : 
    Span    ) -> Unit

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

    set_usage

    source
    fn set_usage(span : 
    Span    , prompt_tokens : Int64, completion_tokens : Int64, cache_read_input_tokens? : Int64, reasoning_output_tokens? : Int64) -> Unit

    Set usage attributes from a GenAI response usage object.

    Sets gen_ai.usage.input_tokens and gen_ai.usage.output_tokens when present. Also sets gen_ai.usage.cache_read.input_tokens and gen_ai.usage.reasoning.output_tokens when provided.

    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, temperature? : Double?, top_p? : Double?, stream? : Bool?, reasoning_level? : String?, stop_sequences? : Array[String]?, frequency_penalty? : Double?, presence_penalty? : Double?, seed? : Int64?, 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.request.temperature (when provided)
    • gen_ai.request.top_p (when provided)
    • gen_ai.request.stream (when provided)
    • gen_ai.request.reasoning.level (when provided)
    • gen_ai.request.stop_sequences (when provided)
    • gen_ai.request.frequency_penalty (when provided)
    • gen_ai.request.presence_penalty (when provided)
    • gen_ai.request.seed (when provided)
    • gen_ai.input.messages (when input_messages is provided)
    • server.address and server.port (when provided)

    start_invoke_agent_span

    source

    Start a span for a GenAI agent invocation within the same process.

    Follows the gen_ai.invoke_agent.internal semantic convention.

    Sets:
    • gen_ai.operation.name = "invoke_agent"
    • gen_ai.agent.name (when provided)

    Span name: invoke_agent {name} or invoke_agent when name is unavailable.

    start_plan_span

    source

    Start a span for an agent planning or task decomposition phase.

    Follows the gen_ai.plan.internal semantic convention.

    Sets:
    • gen_ai.operation.name = "plan"
    • gen_ai.agent.name (when provided)

    Span name: plan {name} or plan when name is unavailable.

    start_span

    source

    Start a new span with the given tracer.

    start_tool_span

    source
    fn start_tool_span(tracer : 
    Tracer    , name : String, arguments : String, call_id? : String?, tool_type? : String?, parent_context? : 
    Context    ) -> 
    Span

    Start a span for a GenAI tool execution following OTel GenAI conventions.

    Sets:
    • gen_ai.operation.name = "execute_tool"
    • gen_ai.tool.name
    • gen_ai.tool.call.arguments
    • gen_ai.tool.call.id (when provided)
    • gen_ai.tool.type (when provided)

    Span name: execute_tool {name}

    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 issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io