Help us shape the future of Go! Take the 2026 Go Developer Survey

observability

package
v1.0.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultRecentCapacity = 500
View Source 
const MaxStagesPerExecution = 16

Variables

This section is empty.

Functions

func AddStageEvents 

func AddStageEvents(span trace.Span, toolStartedAt time.Time, stages []StageRecord)

CloseExecution 关闭当前调用的阶段收集并返回按开始时间排序的快照。 后续异步 Goroutine 的迟到打点会被忽略，避免 child stage 超出父 Tool 生命周期。 AddStageEvents projects the existing lightweight stage model into OpenTelemetry without creating another child-span tree. Event timestamps are the actual stage completion times derived from the parent Tool start.

func RecordStage 

func RecordStage(ctx context.Context, name Stage, startedAt time.Time, success bool)

RecordStage 记录固定枚举阶段。未知名称、缺失 execution 或已结束调用都会安全忽略。

func TraceIdentifiers 

func TraceIdentifiers(parentCtx, activeCtx context.Context) (string, string)

TraceIdentifiers 返回当前 TraceID 与“本次调用实际创建的”SpanID。 默认 no-op tracer 会原样保留上游 SpanContext；这种情况下只关联 TraceID， 不把上游 SpanID 冒充成本地 child span。

func WithExecution 

func WithExecution(ctx context.Context, startedAt time.Time) context.Context

WithExecution 为当前 Tool 调用附加本进程阶段收集状态。 该状态只在 Runtime.Call 生命周期内有效，不承担跨进程 tracing。

func WithSource 

func WithSource(ctx context.Context, source Source) context.Context

Types

type DiagnosticCall 

type DiagnosticCall struct {
	ID            string            `json:"id"`
	Tool          string            `json:"tool"`
	Source        string            `json:"source"`
	TraceID       string            `json:"trace_id,omitempty"`
	StartedAt     time.Time         `json:"started_at"`
	DurationMS    float64           `json:"duration_ms"`
	Success       bool              `json:"success"`
	ErrorCode     string            `json:"error_code,omitempty"`
	ErrorCategory string            `json:"error_category,omitempty"`
	Stages        []DiagnosticStage `json:"stages,omitempty"`
}

DiagnosticCall 是 Nexus 远程诊断消费的最小调用视图。 不包含 SpanID、参数、结果、命令、路径、错误正文或其他 Payload。

func ProjectDiagnostics 

func ProjectDiagnostics(records []ExecutionRecord) []DiagnosticCall

ProjectDiagnostics 把本地运行分析模型裁剪成稳定的远程诊断契约。

type DiagnosticStage 

type DiagnosticStage struct {
	Name            string  `json:"name"`
	StartedOffsetMS float64 `json:"started_offset_ms"`
	DurationMS      float64 `json:"duration_ms"`
	Success         bool    `json:"success"`
}

DiagnosticStage 是远程诊断允许跨进程暴露的阶段字段。 它有意与 StageRecord 分离，避免未来给本地阶段模型增加字段时扩大远程契约。

type ExecutionRecord 

type ExecutionRecord struct {
	ID            uint64        `json:"id"`
	Tool          string        `json:"tool"`
	Source        Source        `json:"source"`
	TraceID       string        `json:"trace_id,omitempty"`
	SpanID        string        `json:"span_id,omitempty"`
	StartedAt     time.Time     `json:"started_at"`
	DurationMS    float64       `json:"duration_ms"`
	Success       bool          `json:"success"`
	ErrorCode     string        `json:"error_code,omitempty"`
	ErrorCategory string        `json:"error_category,omitempty"`
	Stages        []StageRecord `json:"stages,omitempty"`
}

ExecutionRecord 是运行分析保存的最小工具调用元数据。 这里有意不包含参数、结果、错误正文或路径等 Payload。

type ProcessSnapshot 

type ProcessSnapshot struct {
	Goroutines     int    `json:"goroutines"`
	HeapAllocBytes uint64 `json:"heap_alloc_bytes"`
	HeapInuseBytes uint64 `json:"heap_inuse_bytes"`
	HeapSysBytes   uint64 `json:"heap_sys_bytes"`
	GCCycles       uint32 `json:"gc_cycles"`
	UptimeMS       int64  `json:"uptime_ms"`
}

type Recorder 

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

func NewRecorder 

func NewRecorder(capacity int) *Recorder

func (*Recorder) BeginTool 

func (r *Recorder) BeginTool()

func (*Recorder) EndTool 

func (r *Recorder) EndTool(
	tool string,
	source Source,
	startedAt time.Time,
	duration time.Duration,
	success bool,
	errorCode string,
	errorCategory string,
	traceID string,
	spanID string,
	stages []StageRecord,
)

func (*Recorder) RecentCalls 

func (r *Recorder) RecentCalls() []ExecutionRecord

RecentCalls 返回当前内存环里最近调用的独立副本，不计算百分位或进程指标。

func (*Recorder) Snapshot 

func (r *Recorder) Snapshot() Snapshot

type Snapshot 

type Snapshot struct {
	StartedAt      time.Time         `json:"started_at"`
	RecentCapacity int               `json:"recent_capacity"`
	WindowCalls    int               `json:"window_calls"`
	TotalCalls     uint64            `json:"total_calls"`
	TotalErrors    uint64            `json:"total_errors"`
	ActiveCalls    int               `json:"active_calls"`
	ToolStats      []ToolStats       `json:"tool_stats"`
	RecentCalls    []ExecutionRecord `json:"recent_calls"`
	Process        ProcessSnapshot   `json:"process"`
}

type Source 

type Source string

Source 标识一次工具调用进入 Runtime 的传输来源。 来源只允许固定枚举，避免把任意请求数据带入观测记录。 

const (
	SourceInternal Source = "internal"
	SourceMCP      Source = "mcp"
	SourceNexus    Source = "nexus"
)

func SourceFromContext 

func SourceFromContext(ctx context.Context) Source

type Stage 

type Stage string
const (
	StageMCPRefresh            Stage = "mcp.refresh"
	StageMCPRemoteCall         Stage = "mcp.remote_call"
	StageCommandStart          Stage = "command.start"
	StageCommandForegroundWait Stage = "command.foreground_wait"
)

type StageRecord 

type StageRecord struct {
	Name            Stage   `json:"name"`
	StartedOffsetMS float64 `json:"started_offset_ms"`
	DurationMS      float64 `json:"duration_ms"`
	Success         bool    `json:"success"`
}

StageRecord 只描述一次 Tool 调用中的固定阶段耗时。 不允许记录参数、结果、命令、路径、错误正文或其他 Payload。

func CloseExecution 

func CloseExecution(ctx context.Context) []StageRecord

type ToolStats 

type ToolStats struct {
	Tool          string  `json:"tool"`
	Count         int     `json:"count"`
	ErrorCount    int     `json:"error_count"`
	ErrorRate     float64 `json:"error_rate"`
	P50DurationMS float64 `json:"p50_duration_ms"`
	P95DurationMS float64 `json:"p95_duration_ms"`
	P99DurationMS float64 `json:"p99_duration_ms"`
}

type Tracing 

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

Tracing 只持有 OpenTelemetry API 层的 Tracer。 默认使用 no-op 实现，不创建 SDK Provider，也不拥有采样、导出或 Shutdown 生命周期。

func NewTracing 

func NewTracing(tracer trace.Tracer) *Tracing

func (*Tracing) StartTool 

func (t *Tracing) StartTool(ctx context.Context, source Source) (context.Context, trace.Span)

Source Files

View all Source files

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.