Lambda関数での分散トレーシング: OpenTelemetryとAWS X-Rayで可視化の第一歩

# API Gatewayのログを確認
aws logs filter-log-events --log-group-name "API-Gateway-Execution-Logs"

# Lambdaのログを確認  
aws logs filter-log-events --log-group-name "/aws/lambda/LoginFunction"

# 「あれ？このリクエストはどの順番で処理されたんだっけ？」
# 「どこで時間がかかっているんだろう？」

// go.mod
module poc-cognite

go 1.21

require (
    // 既存の依存関係...
    go.opentelemetry.io/otel v1.24.0
    go.opentelemetry.io/otel/trace v1.24.0
    go.opentelemetry.io/otel/sdk v1.24.0
    go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda v0.49.0
)

// pkg/lambda/common_handler.go
type TracingConfig struct {
    ServiceName    string  `json:"service_name"`     // "login", "register"など
    ServiceVersion string  `json:"service_version"`  // "v1.0.0"
    DeploymentEnv  string  `json:"deployment_environment"` // "development", "production"
    SamplingRatio  float64 `json:"sampling_ratio"`   // 0.1 = 10%サンプリング
    EnableTracing  bool    `json:"enable_tracing"`   // true/false
}

# template.yaml（SAMテンプレート）
Globals:
  Function:
    Tracing: Active  # X-Rayトレーシング有効化
    Environment:
      Variables:
        # OpenTelemetryトレーシング設定
        OTEL_SERVICE_NAME: !Sub "${AWS::StackName}"
        OTEL_SERVICE_VERSION: "1.0.0"
        DEPLOYMENT_ENVIRONMENT: !Ref Environment
        OTEL_TRACES_ENABLED: "true"
        OTEL_TRACE_SAMPLING_RATIO: !If 
          - IsProduction
          - "0.1"  # 本番環境では10%サンプリング
          - "1.0"  # 開発環境では100%サンプリング

// cmd/login/main.go（従来版）
func main() {
    config := lambdaCommon.DefaultConfig("login")
    commonHandler := lambdaCommon.NewCommonHandler(config)
    
    // 通常のハンドラー
    wrappedHandler := commonHandler.WrapHandler(businessHandler)
    lambda.Start(wrappedHandler)
}

// cmd/login/main.go（トレーシング対応版）
func main() {
    // ✨ トレーシング対応の設定を使用
    config := lambdaCommon.DefaultConfigWithTracing("login")
    config.AllowedMethods = "POST,OPTIONS"
    
    // 環境変数からトレーシング設定を読み込み
    envTracingConfig := lambdaCommon.TracingConfigFromEnv("login")
    config.TracingConfig = &envTracingConfig

    commonHandler := lambdaCommon.NewCommonHandler(config)

    // 🔍 トレーシング対応ハンドラーを使用
    wrappedHandler := commonHandler.WrapHandlerWithTracing(businessHandler)
    lambda.Start(wrappedHandler)
}

// pkg/lambda/common_handler.go
func (h *CommonHandlerWrapper) WrapHandlerWithTracing(
    businessHandler func(context.Context, events.APIGatewayProxyRequest, *logger.Logger, *middleware.MetricsClient) (events.APIGatewayProxyResponse, error),
) func(context.Context, events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {

    return func(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
        // トレーシングが無効な場合は通常処理
        if !h.tracingConfig.EnableTracing {
            return h.WrapHandler(businessHandler)(ctx, request)
        }

        // 🔍 OpenTelemetryトレーサー取得
        tracer := otel.Tracer(h.tracingConfig.ServiceName)

        // 📊 Lambda handlerスパン開始
        ctx, span := tracer.Start(ctx, "lambda.handler")
        defer span.End()

        // 🏷️ スパン属性設定（セキュリティマスキング対応）
        span.SetAttributes(
            attribute.String("service.name", h.tracingConfig.ServiceName),
            attribute.String("http.method", request.HTTPMethod),
            attribute.String("http.path", request.Path),
            attribute.String("cloud.provider", "aws"),
            attribute.String("faas.trigger", "api_gateway"),
        )

        // 既存の共通ハンドラー処理を実行
        response, err := h.WrapHandler(businessHandler)(ctx, request)

        // 📈 レスポンス情報をスパンに追加
        statusCode := response.StatusCode
        if statusCode == 0 {
            statusCode = 200
        }
        span.SetAttributes(attribute.Int("http.status_code", statusCode))

        // ❌ エラー処理
        if err != nil {
            span.RecordError(err)
            span.SetStatus(codes.Error, err.Error())
        } else if statusCode >= 400 {
            span.SetStatus(codes.Error, fmt.Sprintf("HTTP %d", statusCode))
        } else {
            span.SetStatus(codes.Ok, "")
        }

        return response, err
    }
}

// セキュリティマスキング対応のスパン属性設定
func (h *CommonHandlerWrapper) SetMaskedSpanAttribute(span trace.Span, key, value string) {
    // 既存のセキュリティマスキング機能を活用
    maskedData := map[string]interface{}{key: value}
    masked := logger.MaskSensitiveData(maskedData)

    if maskedMap, ok := masked.(map[string]interface{}); ok {
        if maskedValue, exists := maskedMap[key]; exists {
            span.SetAttributes(attribute.String(key, fmt.Sprintf("%v", maskedValue)))
        }
    }
}

// ❌ 危険：パスワードがそのまま記録される
span.SetAttributes(attribute.String("user_password", "secretPassword123"))

// ✅ 安全：自動マスキングされる
commonHandler.SetMaskedSpanAttribute(span, "user_password", "secretPassword123")
// → 結果: "user_password": "***[MASKED]***"

commonHandler.SetMaskedSpanAttribute(span, "user_email", "user@example.com") 
// → 結果: "user_email": "u***@example.com"

commonHandler.SetMaskedSpanAttribute(span, "api_key", "sk-1234567890abcdef")
// → 結果: "api_key": "sk-****[MASKED]****"

// pkg/lambda/tracing_test.go
func TestTracingIntegration(t *testing.T) {
    // テスト用トレーサープロバイダーの設定
    exporter := tracetest.NewInMemoryExporter()
    tp := trace.NewTracerProvider(
        trace.WithSampler(trace.AlwaysSample()),
        trace.WithBatcher(exporter),
    )
    otel.SetTracerProvider(tp)

    // トレーシング対応ハンドラーで実行
    config := DefaultConfigWithTracing("test-service")
    commonHandler := NewCommonHandler(config)
    handler := commonHandler.WrapHandlerWithTracing(businessHandler)

    // 実行
    response, err := handler(ctx, request)

    // 検証
    assert.NoError(t, err)
    spans := exporter.GetSpans()
    assert.Greater(t, len(spans), 0, "少なくとも1つのスパンが作成されるべきです")
}

// 実装を追加してテストを通す
func (h *CommonHandlerWrapper) WrapHandlerWithTracing(...) {
    // 実装内容
}

// セキュリティマスキング追加
// エラーハンドリング強化
// パフォーマンス最適化

# SAMローカルでテスト
sam local invoke RegisterFunction --event events/register/valid-registration.json --env-vars env-tracing.json

# 出力例：
# {"timestamp":"2025-08-17T13:11:36+09:00","level":"INFO","message":"Request started","service":"register",...}
# トレーシング情報（トレースIDなど）が構造化ログに含まれるため、ローカルでもトレースの開始を確認できます。

aws logs filter-log-events \
  --log-group-name "/aws/lambda/poc-cognite-RegisterFunction" \
  --query 'events[0:3].message'

# 出力例：
# "Request started","service":"register","extra":{"method":"POST","path":"/auth/register"...}

// 現在：AWS X-Ray
// 設定変更のみで以下に移行可能：

// Datadog APM
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.datadoghq.com"

// New Relic  
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.nr-data.net"

// Jaeger（セルフホスト）
export OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:14268/api/traces"

// Phase 1: 重要な関数から開始
LoginFunction    ✅ // ユーザー体験に直結
RegisterFunction ✅ // 登録フローの可視化

// Phase 2: 段階的に拡張  
GetUserFunction     // 次に実装
ChangePasswordFunction // その次...

# 開発環境：詳細なトレーシング
OTEL_TRACE_SAMPLING_RATIO: "1.0"  # 100%

# ステージング環境：適度なトレーシング  
OTEL_TRACE_SAMPLING_RATIO: "0.5"  # 50%

# 本番環境：コスト最適化
OTEL_TRACE_SAMPLING_RATIO: "0.1"  # 10%

// ❌ 絶対にNG
span.SetAttributes(attribute.String("password", userPassword))

// ✅ 推奨
commonHandler.SetMaskedSpanAttribute(span, "user_email", email)