🥮 mooncakes.io
    Sign in

    agent-telemetry

    Download zip
    Version
    0.1.0
    License
    MulanPSL-2.0
    Last updated
    4 months ago
    Downloads
    106

    #agent-telemetry

    MoonBit 的 Agent / LLM / Tool 场景 OpenTelemetry 插桩库。

    把原本需要手写的大量 OTel tracer/span/attribute 样板代码，封装成一组面向业务语义的 helper，让 Agent 开发者只关注何时创建 span、需要记录哪些业务数据。

    #设计分层

    • 薄封装（lib.mbt）：provider 初始化、tracer 缓存、start_span / end_span 等生命周期 helper。
    • 语义封装（genai.mbt / tool.mbt / agent.mbt）：按 OpenTelemetry GenAI semantic conventions 设置属性，覆盖 chat / tool execution / agent turn 三类 span。

    #快速开始

    moon add cybershang/agent-telemetry

    // 初始化 provider
    let exporter = @print.SpanExporter::new().into_span_exporter()
    let config = @telemetry.TelemetryConfig::new(service_name="my-agent")
    let provider = @telemetry.init_telemetry(config, exporter~)

    // 创建 GenAI chat span
    let tracer = @telemetry.tracer("my-agent/llm")
    let span = @telemetry.start_chat_span(
      tracer,
      provider_name="stepfun",
      model="step-3.7-flash",
      max_tokens=1024,
    )
    // ... 发起请求并拿到 response_json ...
    @telemetry.record_chat_response(span, response_json)
    @telemetry.end_span_ok(span)

    #主要 API

    场景函数
    通用TelemetryConfig::new、init_telemetry、tracer、start_span、end_span、end_span_ok、end_span_error
    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

    #测试

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

    #许可证

    Mulan PSL v2

    TelemetryConfig

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

    Configuration for initializing OpenTelemetry in an agent application.

    TelemetryConfig::new

    source
    fn TelemetryConfig::new(otel_stdout? : Bool, otel_endpoint? : String, service_name? : String) -> TelemetryConfig

    Create a new telemetry configuration.

    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_telemetry

    source

    Initialize the global OpenTelemetry tracer provider.

    If exporter is provided, attaches it to a batch span processor. Otherwise builds a no-op provider that discards all spans.

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

    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?, 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

    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.

    Tracers are cached so repeated calls return the same instance.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io