telemetry

package
v0.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 29, 2025 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Agent 相关
	AttrAgentID         = "agent.id"
	AttrAgentName       = "agent.name"
	AttrAgentTemplateID = "agent.template_id"

	// LLM 相关
	AttrLLMProvider     = "llm.provider"
	AttrLLMModel        = "llm.model"
	AttrLLMMaxTokens    = "llm.max_tokens"
	AttrLLMInputTokens  = "llm.usage.input_tokens"
	AttrLLMOutputTokens = "llm.usage.output_tokens"
	AttrLLMTotalTokens  = "llm.usage.total_tokens"

	// Tool 相关
	AttrToolName     = "tool.name"
	AttrToolCallID   = "tool.call_id"
	AttrToolDuration = "tool.duration_ms"
	AttrToolSuccess  = "tool.success"

	// Session 相关
	AttrSessionID    = "session.id"
	AttrUserID       = "user.id"
	AttrInvocationID = "invocation.id"
	AttrBranch       = "agent.branch"
)

常用的预定义属性键（基于 OpenTelemetry 语义约定）

Functions

func Example 

func Example()

Example 演示如何在 Agent 中集成 Telemetry

func ExampleConcurrentAgents 

func ExampleConcurrentAgents()

ExampleConcurrentAgents 演示多 Agent 并发场景

func ExampleWithError 

func ExampleWithError()

ExampleWithError 演示错误处理和追踪

func IncrementCounter 

func IncrementCounter(name string, value int64, labels map[string]string)

便捷函数

func RecordHistogram 

func RecordHistogram(name string, value float64, labels map[string]string)

func SetGauge 

func SetGauge(name string, value float64, labels map[string]string)

func SetGlobalMetrics 

func SetGlobalMetrics(metrics Metrics)

SetGlobalMetrics 设置全局 metrics

func SetGlobalTracer 

func SetGlobalTracer(tracer Tracer)

SetGlobalTracer 设置全局 tracer

Types

type AgentMetrics 

type AgentMetrics struct {
	// contains filtered or unexported fields
}

AgentMetrics Agent 相关的指标收集器

func NewAgentMetrics 

func NewAgentMetrics(metrics Metrics) *AgentMetrics

NewAgentMetrics 创建 Agent metrics

func (*AgentMetrics) RecordError 

func (m *AgentMetrics) RecordError(agentID, errorType string)

RecordError 记录错误

func (*AgentMetrics) RecordRequest 

func (m *AgentMetrics) RecordRequest(agentID string, duration time.Duration)

RecordRequest 记录请求

func (*AgentMetrics) RecordTokens 

func (m *AgentMetrics) RecordTokens(agentID string, inputTokens, outputTokens int64)

RecordTokens 记录 token 使用

func (*AgentMetrics) RecordToolCall 

func (m *AgentMetrics) RecordToolCall(agentID, toolName string, duration time.Duration, success bool)

RecordToolCall 记录工具调用

func (*AgentMetrics) SetActiveAgents 

func (m *AgentMetrics) SetActiveAgents(count int)

SetActiveAgents 设置活跃 Agent 数量

func (*AgentMetrics) SetQueueDepth 

func (m *AgentMetrics) SetQueueDepth(agentID string, depth int)

SetQueueDepth 设置队列深度

type Attribute 

type Attribute struct {
	Key   string
	Value any
}

Attribute 表示 span 的属性

func Bool 

func Bool(key string, value bool) Attribute

func Float64 

func Float64(key string, value float64) Attribute

func Int 

func Int(key string, value int) Attribute

func Int64 

func Int64(key string, value int64) Attribute

func String 

func String(key, value string) Attribute

常用属性构造函数

type CounterSnapshot 

type CounterSnapshot struct {
	Name   string
	Value  int64
	Labels map[string]string
}

CounterSnapshot 计数器快照

type GaugeSnapshot 

type GaugeSnapshot struct {
	Name   string
	Value  float64
	Labels map[string]string
}

GaugeSnapshot 仪表盘快照

type HistogramSnapshot 

type HistogramSnapshot struct {
	Name   string
	Count  int64
	Sum    float64
	Min    float64
	Max    float64
	Mean   float64
	Labels map[string]string
}

HistogramSnapshot 直方图快照

type Metrics 

type Metrics interface {
	// Counter 操作
	IncrementCounter(name string, value int64, labels map[string]string)

	// Gauge 操作
	SetGauge(name string, value float64, labels map[string]string)

	// Histogram 操作
	RecordHistogram(name string, value float64, labels map[string]string)

	// 获取指标快照
	Snapshot() MetricsSnapshot
}

Metrics 提供指标收集能力 参考 Google ADK-Go 的 metrics 设计

func GetGlobalMetrics 

func GetGlobalMetrics() Metrics

GetGlobalMetrics 获取全局 metrics

type MetricsSnapshot 

type MetricsSnapshot struct {
	Counters   map[string]*CounterSnapshot
	Gauges     map[string]*GaugeSnapshot
	Histograms map[string]*HistogramSnapshot
	Timestamp  time.Time
}

MetricsSnapshot 指标快照

type NoopSpan 

type NoopSpan struct{}

NoopSpan 空实现的 span

func (*NoopSpan) AddEvent 

func (s *NoopSpan) AddEvent(name string, attrs ...Attribute)

func (*NoopSpan) End 

func (s *NoopSpan) End()

func (*NoopSpan) RecordError 

func (s *NoopSpan) RecordError(err error)

func (*NoopSpan) SetAttributes 

func (s *NoopSpan) SetAttributes(attrs ...Attribute)

func (*NoopSpan) SetStatus 

func (s *NoopSpan) SetStatus(code StatusCode, description string)

func (*NoopSpan) SpanContext 

func (s *NoopSpan) SpanContext() SpanContext

type NoopSpanContext 

type NoopSpanContext struct{}

NoopSpanContext 空实现的 span context

func (*NoopSpanContext) IsSampled 

func (c *NoopSpanContext) IsSampled() bool

func (*NoopSpanContext) SpanID 

func (c *NoopSpanContext) SpanID() string

func (*NoopSpanContext) TraceID 

func (c *NoopSpanContext) TraceID() string

type NoopTracer 

type NoopTracer struct{}

NoopTracer 空实现的 tracer，用于禁用追踪

func (*NoopTracer) Extract 

func (t *NoopTracer) Extract(ctx context.Context, carrier any) context.Context

func (*NoopTracer) Inject 

func (t *NoopTracer) Inject(ctx context.Context, carrier any) error

func (*NoopTracer) StartSpan 

func (t *NoopTracer) StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

type OTelOption 

type OTelOption func(*otelConfig)

OTelOption 配置 OpenTelemetry tracer 的选项

func WithOTelAttributes 

func WithOTelAttributes(attrs ...attribute.KeyValue) OTelOption

WithOTelAttributes 设置额外的 resource 属性

func WithOTelExporter 

func WithOTelExporter(exporter sdktrace.SpanExporter) OTelOption

WithOTelExporter 设置 trace exporter

func WithOTelSampler 

func WithOTelSampler(sampler sdktrace.Sampler) OTelOption

WithOTelSampler 设置采样器

func WithOTelServiceVersion 

func WithOTelServiceVersion(version string) OTelOption

WithOTelServiceVersion 设置服务版本

func WithOTelSpanProcessor 

func WithOTelSpanProcessor(processor sdktrace.SpanProcessor) OTelOption

WithOTelSpanProcessor 添加自定义 span processor

type OTelSpan 

type OTelSpan struct {
	// contains filtered or unexported fields
}

OTelSpan 适配 Span 接口

func (*OTelSpan) AddEvent 

func (s *OTelSpan) AddEvent(name string, attrs ...Attribute)

AddEvent 实现 Span 接口

func (*OTelSpan) End 

func (s *OTelSpan) End()

End 实现 Span 接口

func (*OTelSpan) RecordError 

func (s *OTelSpan) RecordError(err error)

RecordError 实现 Span 接口

func (*OTelSpan) SetAttributes 

func (s *OTelSpan) SetAttributes(attrs ...Attribute)

SetAttributes 实现 Span 接口

func (*OTelSpan) SetStatus 

func (s *OTelSpan) SetStatus(code StatusCode, description string)

SetStatus 实现 Span 接口

func (*OTelSpan) SpanContext 

func (s *OTelSpan) SpanContext() SpanContext

SpanContext 实现 Span 接口

type OTelSpanContext 

type OTelSpanContext struct {
	// contains filtered or unexported fields
}

OTelSpanContext 适配 SpanContext 接口

func (*OTelSpanContext) IsSampled 

func (c *OTelSpanContext) IsSampled() bool

IsSampled 实现 SpanContext 接口

func (*OTelSpanContext) SpanID 

func (c *OTelSpanContext) SpanID() string

SpanID 实现 SpanContext 接口

func (*OTelSpanContext) TraceID 

func (c *OTelSpanContext) TraceID() string

TraceID 实现 SpanContext 接口

type OTelTracer 

type OTelTracer struct {
	// contains filtered or unexported fields
}

OTelTracer 实现 Tracer 接口，适配 OpenTelemetry 参考 Google ADK-Go 的 telemetry/telemetry.go 实现

使用示例: 

// 1. 创建 OTel tracer
tracer, err := telemetry.NewOTelTracer("my-agent-service",
    telemetry.WithOTelExporter(exporter),
)

// 2. 设置为全局 tracer
telemetry.SetGlobalTracer(tracer)

// 3. 在代码中使用
ctx, span := tracer.StartSpan(ctx, "agent.chat")
defer span.End()

func NewOTelTracer 

func NewOTelTracer(serviceName string, opts ...OTelOption) (*OTelTracer, error)

NewOTelTracer 创建 OpenTelemetry 追踪器

func (*OTelTracer) Extract 

func (t *OTelTracer) Extract(ctx context.Context, carrier any) context.Context

Extract 从 carrier 中提取 trace context

func (*OTelTracer) ForceFlush 

func (t *OTelTracer) ForceFlush(ctx context.Context) error

ForceFlush 强制刷新所有待处理的 spans

func (*OTelTracer) Inject 

func (t *OTelTracer) Inject(ctx context.Context, carrier any) error

Inject 将 trace context 注入到 carrier

func (*OTelTracer) Shutdown 

func (t *OTelTracer) Shutdown(ctx context.Context) error

Shutdown 关闭 tracer，刷新所有待处理的 spans

func (*OTelTracer) StartSpan 

func (t *OTelTracer) StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

StartSpan 实现 Tracer 接口

type SimpleMetrics 

type SimpleMetrics struct {
	// contains filtered or unexported fields
}

SimpleMetrics 简单的内存 metrics 实现

func NewSimpleMetrics 

func NewSimpleMetrics() *SimpleMetrics

NewSimpleMetrics 创建简单的 metrics 实例

func (*SimpleMetrics) IncrementCounter 

func (m *SimpleMetrics) IncrementCounter(name string, value int64, labels map[string]string)

func (*SimpleMetrics) RecordHistogram 

func (m *SimpleMetrics) RecordHistogram(name string, value float64, labels map[string]string)

func (*SimpleMetrics) SetGauge 

func (m *SimpleMetrics) SetGauge(name string, value float64, labels map[string]string)

func (*SimpleMetrics) Snapshot 

func (m *SimpleMetrics) Snapshot() MetricsSnapshot

type SimpleSpan 

type SimpleSpan struct {
	// contains filtered or unexported fields
}

SimpleSpan 简单的 span 实现

func (*SimpleSpan) AddEvent 

func (s *SimpleSpan) AddEvent(name string, attrs ...Attribute)

func (*SimpleSpan) Attributes 

func (s *SimpleSpan) Attributes() []Attribute

func (*SimpleSpan) Duration 

func (s *SimpleSpan) Duration() time.Duration

func (*SimpleSpan) End 

func (s *SimpleSpan) End()

func (*SimpleSpan) EndTime 

func (s *SimpleSpan) EndTime() time.Time

func (*SimpleSpan) Error 

func (s *SimpleSpan) Error() error

func (*SimpleSpan) Events 

func (s *SimpleSpan) Events() []SpanEvent

func (*SimpleSpan) Name 

func (s *SimpleSpan) Name() string

获取 span 信息 (用于测试和调试)

func (*SimpleSpan) RecordError 

func (s *SimpleSpan) RecordError(err error)

func (*SimpleSpan) SetAttributes 

func (s *SimpleSpan) SetAttributes(attrs ...Attribute)

func (*SimpleSpan) SetStatus 

func (s *SimpleSpan) SetStatus(code StatusCode, description string)

func (*SimpleSpan) SpanContext 

func (s *SimpleSpan) SpanContext() SpanContext

func (*SimpleSpan) StartTime 

func (s *SimpleSpan) StartTime() time.Time

func (*SimpleSpan) Status 

func (s *SimpleSpan) Status() StatusCode

func (*SimpleSpan) StatusDescription 

func (s *SimpleSpan) StatusDescription() string

type SimpleSpanContext 

type SimpleSpanContext struct {
	// contains filtered or unexported fields
}

SimpleSpanContext 简单的 span context 实现

func (*SimpleSpanContext) IsSampled 

func (c *SimpleSpanContext) IsSampled() bool

func (*SimpleSpanContext) SpanID 

func (c *SimpleSpanContext) SpanID() string

func (*SimpleSpanContext) TraceID 

func (c *SimpleSpanContext) TraceID() string

type SimpleTracer 

type SimpleTracer struct {
	// contains filtered or unexported fields
}

SimpleTracer 简单的内存 tracer 实现 用于开发和测试环境

func NewSimpleTracer 

func NewSimpleTracer() *SimpleTracer

func (*SimpleTracer) Extract 

func (t *SimpleTracer) Extract(ctx context.Context, carrier any) context.Context

func (*SimpleTracer) GetSpans 

func (t *SimpleTracer) GetSpans() []*SimpleSpan

GetSpans 获取所有 span (用于测试)

func (*SimpleTracer) Inject 

func (t *SimpleTracer) Inject(ctx context.Context, carrier any) error

func (*SimpleTracer) StartSpan 

func (t *SimpleTracer) StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

type Span 

type Span interface {
	// End 结束 span
	End()

	// SetAttributes 设置属性
	SetAttributes(attrs ...Attribute)

	// SetStatus 设置状态
	SetStatus(code StatusCode, description string)

	// AddEvent 添加事件
	AddEvent(name string, attrs ...Attribute)

	// RecordError 记录错误
	RecordError(err error)

	// SpanContext 返回 span context
	SpanContext() SpanContext
}

Span 表示一个追踪片段

func StartSpan 

func StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

StartSpan 使用全局 tracer 开始 span

type SpanConfig 

type SpanConfig struct {
	Kind       SpanKind
	Attributes []Attribute
	StartTime  time.Time
}

SpanConfig span 配置

type SpanContext 

type SpanContext interface {
	TraceID() string
	SpanID() string
	IsSampled() bool
}

SpanContext 表示 span 的上下文信息

type SpanEvent 

type SpanEvent struct {
	Name       string
	Timestamp  time.Time
	Attributes []Attribute
}

type SpanKind 

type SpanKind int

SpanKind span 类型 

const (
	SpanKindInternal SpanKind = iota
	SpanKindServer
	SpanKindClient
	SpanKindProducer
	SpanKindConsumer
)

type SpanOption 

type SpanOption func(*SpanConfig)

SpanOption 配置 span 的选项

func WithAttributes 

func WithAttributes(attrs ...Attribute) SpanOption

WithAttributes 设置初始属性

func WithSpanKind 

func WithSpanKind(kind SpanKind) SpanOption

WithSpanKind 设置 span 类型

func WithTimestamp 

func WithTimestamp(t time.Time) SpanOption

WithTimestamp 设置开始时间

type StatusCode 

type StatusCode int

StatusCode 表示 span 的状态码 

const (
	StatusCodeUnset StatusCode = iota
	StatusCodeOK
	StatusCodeError
)

type Tracer 

type Tracer interface {
	// StartSpan 开始一个新的 span
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

	// Extract 从 carrier 中提取 trace context
	Extract(ctx context.Context, carrier any) context.Context

	// Inject 将 trace context 注入到 carrier
	Inject(ctx context.Context, carrier any) error
}

Tracer 提供分布式追踪能力 参考 Google ADK-Go 的 OpenTelemetry 集成

func GetGlobalTracer 

func GetGlobalTracer() Tracer

GetGlobalTracer 获取全局 tracer

Source Files

View all Source files

Directories

Path Synopsis
Package genai provides OpenTelemetry GenAI Semantic Conventions for Aster.
 Package genai provides OpenTelemetry GenAI Semantic Conventions for Aster.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.