AgentSkillsCN

observability

结合 OpenTelemetry 进行链路追踪，配合 slog 实现结构化日志记录。适用于为服务、处理器，或生产环境中的疑难问题添加可观测性时使用。

SKILL.md
--- frontmatter
name: observability
description: Tracing with OpenTelemetry and structured logging with slog. Use when adding observability to services, handlers, or debugging production issues.
userInvokable: true

Observability

References: Examples

Tracing (OpenTelemetry)

Example

Mandatory for: repositories, API clients, Lambdas, usecases

go
func (s *Service) GetOrder(ctx context.Context, id string) (*Order, error) {
    ctx, span := tracing.StartSpan(ctx, "Service.GetOrder")
    defer span.End()

    span.SetAttributes(attribute.String("order.id", id))
    // business logic...
}

Structured Logging (slog)

Example

Use log/slog with structured JSON:

go
slog.InfoContext(ctx, "order retrieved",
    "order_id", orderID,
    "reference_id", referenceID,
)

Log Levels

LevelUse When
INFONormal operations, successful requests
WARNRecoverable errors, degraded state, fallbacks used
ERRORFailures requiring attention, unrecoverable errors

Lambda Lifecycle

Example

go
func main() {
    ctx := context.Background()

    otelShutdown, err := otel.Setup(ctx)
    if err != nil {
        fmt.Printf("Error setting up OpenTelemetry: %v\n", err)
        os.Exit(1)
    }

    defer func() {
        if err := otelShutdown(context.Background()); err != nil {
            fmt.Printf("Error shutting down: %v\n", err)
        }
    }()

    lambda.Start(otellambda.InstrumentHandler(handler))
}

HTTP Client Tracing

Example

go
client := tracing.NewRestyClient(baseURL,
    tracing.WithTimeout(30*time.Second),
    tracing.WithRetryCount(3),
)