Go LLM 应用自定义埋点最佳实践

事件发送（Events）

util-genai 支持通过 OTel Logs API 发送 GenAI 事件。当 StopLLM / StopInvokeAgent 被调用时，如果同时满足以下条件，Handler 会自动向 LoggerProvider 发送一条事件（event name 为 gen_ai.client.inference.operation.details 或 gen_ai.client.agent.invoke.operation.details）：

• 环境变量 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental 已设置。

• 环境变量 OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT=true 已设置。

• 创建 Handler 时通过 WithLoggerProvider(lp) 注入了 LoggerProvider。

消息内容仅在 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 包含 EVENT（即 EVENT_ONLY 或 SPAN_AND_EVENT）时才落入事件体。

export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
export OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT=true
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY

import (
    logapi "go.opentelemetry.io/otel/log"
    sdklog "go.opentelemetry.io/otel/sdk/log"
    "go.opentelemetry.io/otel/exporters/stdout/stdoutlog"
)

logExporter, _ := stdoutlog.New()
lp := sdklog.NewLoggerProvider(sdklog.WithProcessor(
    sdklog.NewBatchProcessor(logExporter),
))
defer lp.Shutdown(ctx)

handler := utilgenai.NewTelemetryHandler(
    utilgenai.WithTracerProvider(tp),
    utilgenai.WithLoggerProvider(lp),
)

之后使用 Handler 的 StartLLM / StopLLM 与 StartInvokeAgent / StopInvokeAgent 照常调用即可，事件会自动发送，无需额外代码。

内容卸载（CompletionHook）

当 LLM 的 prompt/response 体积较大时（如数十 KB 的多轮对话上下文），直接写入 Span Attribute 可能导致 Span 过大。util-genai 提供了 CompletionHook 接口，在 StopLLM 时自动将大 payload 异步卸载到外部存储（文件系统或自定义后端），仅在 Span 中写入一个 content-addressed 引用 URI（gen_ai.input.messages_ref / gen_ai.output.messages_ref 等）。

内置的 UploadCompletionHook 使用 SHA-256 计算文件名实现去重（同一 payload 不重复写），支持 JSON 和 JSONL 两种序列化格式，内部通过 worker pool + bounded FIFO set 实现异步并发上传。

# 配置外部存储路径与格式
export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH=/data/genai-traces
export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT=json
export OTEL_INSTRUMENTATION_GENAI_UPLOAD_MAX_QUEUE_SIZE=128

// 使用内置 FS Uploader（也可以实现自定义 Uploader 接口写入 OSS 等）
hook := utilgenai.NewUploadCompletionHook(
    utilgenai.WithUploader(utilgenai.NewFSUploader("/data/genai-traces")),
    utilgenai.WithUploadFormat(utilgenai.UploadFormatJSON),
    utilgenai.WithUploadQueueSize(128),
)

handler := utilgenai.NewTelemetryHandler(
    utilgenai.WithTracerProvider(tp),
    utilgenai.WithCompletionHook(hook),
)
defer handler.Shutdown(ctx) // 优雅 drain 队列中的 pending 上传

当 StopLLM 完成后，Handler 内部调用 offloadLLMContent 将 InputMessages、OutputMessages、SystemInstruction、ToolDefinitions 序列化并提交给 CompletionHook。Hook 计算 SHA-256，写入文件系统（如 /data/genai-traces/<sha256>.json），并在 Span 上写入引用属性 gen_ai.input.messages_ref=sha256://<hash>。

自定义 Uploader 接口：

type Uploader interface {
    Upload(ctx context.Context, ref string, data []byte) error
}

可以实现该接口将 payload 写入 OSS、S3 或其他对象存储。

Reasoning 消息类型

util-genai 新增了 Reasoning 消息片段类型，用于承载模型的推理/思考过程（如 Chain-of-Thought）。在 OutputMessage.Parts 中使用：

invocation.OutputMessages = []utilgenai.OutputMessage{{
    Role: "assistant",
    Parts: []utilgenai.MessagePart{
        utilgenai.Reasoning{Content: "让我分析这个问题...首先..."},
        utilgenai.Text{Content: "最终回答是..."},
    },
    FinishReason: utilgenai.FinishReasonStop,
}}
// Reasoning token 可通过 ReasoningOutputTokens 单独统计
reasoningTokens := 150
invocation.ReasoningOutputTokens = &reasoningTokens

对应的 Span 属性为 gen_ai.usage.reasoning.output_tokens，在控制台中可区分模型的推理 Token 与正式输出 Token。

Entry Span 详情

Entry Span 详情面板中，关键属性包括 gen_ai.session.id（会话唯一标识）和 gen_ai.user.id（用户标识），在函数入口处设置后会自动透传到下游子 Span（前提是下游 Span 使用同一 Context 派生）。同时可查看 gen_ai.input.messages（用户输入的完整消息内容）和 gen_ai.output.messages（模型最终输出的完整消息内容）。

Agent Span 详情

Agent Span 面板展示该 Agent 的名称与描述，以及 Agent 级别的 Token 用量汇总。示例中：gen_ai.agent.name=TechContentAgent、gen_ai.provider.name=dashscope、gen_ai.request.model=qwen-plus、gen_ai.usage.input_tokens=3982、gen_ai.usage.output_tokens=884。

Tool Span 详情

Tool Span 展示工具调用的详细信息。以 execute_tool generate_seo_keywords 为例，右侧详情面板显示工具名称（gen_ai.tool.name=generate_seo_keywords）、工具类型（gen_ai.tool.type=function）、工具调用入参（gen_ai.tool.call.arguments）以及工具返回结果（gen_ai.tool.call.result），便于排查工具调用的输入输出是否符合预期。

LLM Span 详情

LLM Span 可以由 ARMS 探针对已支持的 Go 组件（如 sashabaranov/go-openai、dashscope 等）自动采集，也可以通过本文示例中的 LLMInvocation 手动创建。自动采集适用于常见文本对话模型调用；对于 ASR、TTS 等暂未由探针自动覆盖或需要补充业务属性的模型调用，可以手动创建 LLM Span 并写入 gen_ai.asr.* / gen_ai.tts.* 等自定义属性。

LLM Span 详情面板展示应用名、接口名、IP、开始与结束时间、SpanID、ParentSpanID、状态码等基本信息。附加信息选项卡可查看该次调用的 response 输出内容、自定义 Attribute 和 Token 用量。

自定义 Span 详情

自定义 Span（如 duplicate_tool_detection、response_loop_detection）需要在控制台调用链视图切换到全部视图才能看到；面板中可查看写入的 gen_ai.loop_detection.* 属性，用于分析业务侧循环、重试等异常行为。

main.go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"
    "strings"
    "time"

    utilgenai "github.com/alibaba/loongsuite-go/util-genai"
    openai "github.com/sashabaranov/go-openai"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
    "go.opentelemetry.io/otel/trace"
)

func initTracer(ctx context.Context) (*sdktrace.TracerProvider, error) {
    exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
    if err != nil {
        return nil, err
    }
    res, err := resource.New(ctx,
        resource.WithAttributes(
            semconv.ServiceNameKey.String("techcontent-agent"),
            semconv.ServiceVersionKey.String("0.1.0"),
            // 关键 Resource：不要通过 Span Attribute 写
            attribute.String("acs.arms.service.feature", "genai_app"),
            attribute.String("gen_ai.instrumentation.sdk.name", "loongsuite-genai-utils"),
        ),
    )
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(res),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}

func main() {
    ctx := context.Background()
    tp, err := initTracer(ctx)
    if err != nil {
        log.Fatalf("init tracer: %v", err)
    }
    defer tp.Shutdown(ctx)

    apiKey := os.Getenv("DASHSCOPE_API_KEY")
    if apiKey == "" {
        log.Fatal("DASHSCOPE_API_KEY is required")
    }

    cfg := openai.DefaultConfig(apiKey)
    cfg.BaseURL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
    client := openai.NewClientWithConfig(cfg)

    handler := utilgenai.NewTelemetryHandler(utilgenai.WithTracerProvider(tp))
    tracer := otel.Tracer("techcontent-agent")

    if err := runAgent(ctx, client, handler, tracer, "CMS 2.0 AI 告警降噪"); err != nil {
        log.Fatalf("run agent: %v", err)
    }
}

func runAgent(
    ctx context.Context,
    client *openai.Client,
    handler *utilgenai.TelemetryHandler,
    tracer trace.Tracer,
    topic string,
) error {
    // ---------- Entry Span ----------
    sessionID := fmt.Sprintf("sess-%d", time.Now().UnixNano())
    ctx, entrySpan := tracer.Start(ctx, "enter",
        trace.WithSpanKind(trace.SpanKindServer),
        trace.WithAttributes(
            attribute.String("gen_ai.span.kind", "ENTRY"),
            attribute.String("gen_ai.operation.name", "enter"),
            attribute.String("gen_ai.session.id", sessionID),
            attribute.String("gen_ai.user.id", "anonymous"),
        ),
    )
    defer entrySpan.End()

    inputMsgs := []utilgenai.InputMessage{
        {Role: "user", Parts: []utilgenai.MessagePart{utilgenai.Text{Content: topic}}},
    }
    entrySpan.SetAttributes(
        attribute.String("gen_ai.input.messages", utilgenai.InputMessagesToJSON(inputMsgs)),
    )

    // ---------- Agent Span ----------
    agentInv := utilgenai.NewInvokeAgentInvocation()
    agentInv.Provider = "dashscope"
    agentInv.AgentName = "TechContentAgent"
    agentInv.AgentDescription = "技术内容生成助手"
    agentInv.RequestModel = "qwen-plus"
    agentInv.ConversationID = sessionID

    ctx = handler.StartInvokeAgent(ctx, agentInv)

    messages := []openai.ChatCompletionMessage{
        {Role: openai.ChatMessageRoleSystem, Content: "你是一名资深云原生技术编辑，善用工具收集素材后再撰稿。"},
        {Role: openai.ChatMessageRoleUser, Content: topic},
    }

    var (
        totalIn, totalOut int
        finalContent     string
        toolCounter      = map[string]int{}
        prevContent      string
    )

    // ---------- ReAct 循环 ----------
    for round := 0; round < 5; round++ {
        checkDuplicateTools(ctx, tracer, toolCounter, &messages)

        stepCtx, stepSpan := tracer.Start(ctx, "react",
            trace.WithSpanKind(trace.SpanKindInternal),
            trace.WithAttributes(
                attribute.String("gen_ai.span.kind", "STEP"),
                attribute.String("gen_ai.operation.name", "react"),
                attribute.Int("gen_ai.step.round", round+1),
            ),
        )

        // 手工 LLM Span（若已启用 ARMS Go 自动埋点可省略）
        llmInv := utilgenai.NewLLMInvocation("qwen-plus")
        llmInv.Provider = "dashscope"
        llmInv.OperationName = utilgenai.OperationChat
        llmInv.ConversationID = sessionID
        llmInv.InputMessages = openAIToUtilMessages(messages)

        stepCtx = handler.StartLLM(stepCtx, llmInv)
        resp, err := client.CreateChatCompletion(stepCtx, openai.ChatCompletionRequest{
            Model:    "qwen-plus",
            Messages: messages,
            Tools:    toolDefinitions(),
        })
        if err != nil {
            handler.FailLLM(llmInv, &utilgenai.Error{Message: err.Error(), Type: "APIError"})
            stepSpan.RecordError(err)
            stepSpan.End()
            handler.FailInvokeAgent(agentInv, &utilgenai.Error{Message: err.Error(), Type: "APIError"})
            return err
        }

        choice := resp.Choices[0]
        llmInv.ResponseID = resp.ID
        llmInv.ResponseModelName = resp.Model
        pt := resp.Usage.PromptTokens
        ct := resp.Usage.CompletionTokens
        llmInv.InputTokens = &pt
        llmInv.OutputTokens = &ct
        totalIn += pt
        totalOut += ct

        llmInv.OutputMessages = []utilgenai.OutputMessage{{
            Role:         "assistant",
            Parts:        []utilgenai.MessagePart{utilgenai.Text{Content: choice.Message.Content}},
            FinishReason: utilgenai.FinishReason(choice.FinishReason),
        }}
        handler.StopLLM(llmInv)

        messages = append(messages, choice.Message)

        // ---------- Tool 循环 ----------
        for _, tc := range choice.Message.ToolCalls {
            toolCounter[tc.Function.Name]++
            toolInv := utilgenai.NewExecuteToolInvocation(tc.Function.Name)
            toolInv.ToolCallID = tc.ID
            toolInv.ToolType = "function"

            _ = json.Unmarshal([]byte(tc.Function.Arguments), &toolInv.Input)

            stepCtx = handler.StartExecuteTool(stepCtx, toolInv)
            result, err := dispatchTool(tc.Function.Name, tc.Function.Arguments)
            if err != nil {
                handler.FailExecuteTool(toolInv, &utilgenai.Error{Message: err.Error(), Type: "ToolError"})
                stepSpan.End()
                handler.FailInvokeAgent(agentInv, &utilgenai.Error{Message: err.Error(), Type: "ToolError"})
                return err
            }
            toolInv.Output = result
            handler.StopExecuteTool(toolInv)

            messages = append(messages, openai.ChatCompletionMessage{
                Role:       openai.ChatMessageRoleTool,
                Content:    result,
                ToolCallID: tc.ID,
                Name:       tc.Function.Name,
            })
        }

        // ReAct 结束判断
        finishReason := "continue"
        if len(choice.Message.ToolCalls) == 0 {
            finishReason = "stop"
            finalContent = choice.Message.Content
            stepSpan.SetAttributes(attribute.String("gen_ai.response.finish_reason", finishReason))
            stepSpan.End()

            if checkResponseLoop(ctx, tracer, finalContent, prevContent) {
                agentInv.Attributes = map[string]any{
                    "gen_ai.response.finish_reason": "loop_detected",
                }
                break
            }
            break
        }
        stepSpan.SetAttributes(attribute.String("gen_ai.response.finish_reason", finishReason))
        stepSpan.End()
        prevContent = choice.Message.Content
    }

    // 汇总 Token 用量并结束 Agent Span
    agentInv.InputTokens = &totalIn
    agentInv.OutputTokens = &totalOut
    handler.StopInvokeAgent(agentInv)

    // Entry 输出
    outputMsgs := []utilgenai.OutputMessage{{
        Role:         "assistant",
        Parts:        []utilgenai.MessagePart{utilgenai.Text{Content: finalContent}},
        FinishReason: utilgenai.FinishReasonStop,
    }}
    entrySpan.SetAttributes(
        attribute.String("gen_ai.output.messages", utilgenai.OutputMessagesToJSON(outputMsgs)),
    )

    fmt.Println(strings.Repeat("-", 60))
    fmt.Println(finalContent)
    return nil
}

tools.go

package main

import (
    "encoding/json"
    "fmt"

    openai "github.com/sashabaranov/go-openai"
)

func toolDefinitions() []openai.Tool {
    return []openai.Tool{
        {
            Type: openai.ToolTypeFunction,
            Function: &openai.FunctionDefinition{
                Name:        "generate_seo_keywords",
                Description: "根据主题生成 SEO 关键词",
                Parameters: map[string]any{
                    "type": "object",
                    "properties": map[string]any{
                        "topic": map[string]any{"type": "string"},
                    },
                    "required": []string{"topic"},
                },
            },
        },
        {
            Type: openai.ToolTypeFunction,
            Function: &openai.FunctionDefinition{
                Name:        "outline_article",
                Description: "生成文章大纲",
                Parameters: map[string]any{
                    "type": "object",
                    "properties": map[string]any{
                        "topic":    map[string]any{"type": "string"},
                        "keywords": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
                    },
                    "required": []string{"topic"},
                },
            },
        },
    }
}

func dispatchTool(name, argJSON string) (string, error) {
    var args map[string]any
    _ = json.Unmarshal([]byte(argJSON), &args)
    switch name {
    case "generate_seo_keywords":
        topic, _ := args["topic"].(string)
        return fmt.Sprintf(`["%s 最佳实践", "%s 案例分析", "%s 落地方案"]`, topic, topic, topic), nil
    case "outline_article":
        topic, _ := args["topic"].(string)
        return fmt.Sprintf(`## %s 大纲\n1. 背景\n2. 技术方案\n3. 效果度量`, topic), nil
    default:
        return "", fmt.Errorf("unknown tool: %s", name)
    }
}

messages.go

package main

import (
    utilgenai "github.com/alibaba/loongsuite-go/util-genai"
    openai "github.com/sashabaranov/go-openai"
)

func openAIToUtilMessages(msgs []openai.ChatCompletionMessage) []utilgenai.InputMessage {
    out := make([]utilgenai.InputMessage, 0, len(msgs))
    for _, m := range msgs {
        out = append(out, utilgenai.InputMessage{
            Role:  m.Role,
            Parts: []utilgenai.MessagePart{utilgenai.Text{Content: m.Content}},
        })
    }
    return out
}