Observability

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "StrandsAgents",           package: "strands-agents-swift"),
        .product(name: "StrandsBedrockProvider",   package: "strands-agents-swift"),
        .product(name: "StrandsOTelObservability", package: "strands-agents-swift"),
    ]
)

import StrandsAgents
import StrandsOTelObservability

let agent = Agent(
    model: provider,
    tools: [myTool],
    observability: OTelObservabilityEngine.datadog(
        apiKey: "...",   // see API Key Safety section below
        service: "my-app"
    )
)

let result = try await agent.run("What is 42 * 17?")
// Traces appear in Datadog LLM Observability within seconds

OTelObservabilityEngine.datadog(
    apiKey:   "your-dd-api-key",
    service:  "my-app",          // service name shown in Datadog
    version:  "2.1.0",           // optional, defaults to "1.0"
    site:     "datadoghq.eu",    // optional, defaults to "datadoghq.com"
    endpoint: URL(string: "https://your-collector.example.com/v1/traces")
    // endpoint overrides site -- use this for the Collector proxy pattern
)

observability: OTelObservabilityEngine.datadog(
    apiKey: ProcessInfo.processInfo.environment["DD_API_KEY"] ?? "",
    service: "my-app"
)

observability: OTelObservabilityEngine.datadog(
    apiKey: "",   // ignored -- proxy adds the key server-side
    service: "my-app",
    endpoint: URL(string: "https://your-proxy.example.com/v1/traces")
)

export const handler = async (event) => {
  const apiKey = process.env.DD_API_KEY; // set in Lambda, never in app

  const response = await fetch("https://otlp.datadoghq.com/v1/traces", {
    method: "POST",
    headers: {
      "Content-Type": event.headers["content-type"] ?? "application/x-protobuf",
      "dd-api-key": apiKey,
      "dd-otlp-source": "llmobs",
    },
    body: Buffer.from(event.body, event.isBase64Encoded ? "base64" : "utf8"),
  });

  return { statusCode: response.status };
};

aws apigateway create-usage-plan \
  --name "otlp-proxy-plan" \
  --throttle burstLimit=50,rateLimit=10 \
  --quota limit=50000,period=DAY

DD_API_KEY=your_api_key DD_SITE=datadoghq.com \
  bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

docker run -d \
  --name ddot-collector \
  -e DD_API_KEY=your_api_key \
  -e DD_SITE=datadoghq.com \
  -p 4318:4318 \
  -v $(pwd)/otel-config.yaml:/etc/datadog-agent/otel-config.yaml \
  gcr.io/datadoghq/agent:latest

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  datadog:
    api:
      key: ${env:DD_API_KEY}
      site: datadoghq.com   # datadoghq.eu for EU

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [datadog]

// Quick test -- server IP directly
observability: OTelObservabilityEngine.datadog(
    apiKey: "",
    service: "my-app",
    endpoint: URL(string: "http://1.2.3.4:4318/v1/traces")
)

// Production -- domain with TLS
observability: OTelObservabilityEngine.datadog(
    apiKey: "",
    service: "my-app",
    endpoint: URL(string: "https://collector.yourserver.com/v1/traces")
)

import OpenTelemetrySdk
import OpenTelemetryProtocolExporterHttp

let exporter = OtlpHttpTraceExporter(
    endpoint: URL(string: "https://collector.yourbackend.com/v1/traces")!
)
let provider = TracerProviderBuilder()
    .add(spanProcessor: BatchSpanProcessor(spanExporter: exporter))
    .build()
OpenTelemetry.registerTracerProvider(tracerProvider: provider)

let tracer = provider.get(instrumentationName: "my-app", instrumentationVersion: "1.0")
let observability = OTelObservabilityEngine(tracer: tracer)

let result = try await agent.run("Summarize the quarterly report")

// Run-level metrics
print(result.metrics.cycleCount)           // number of reasoning cycles
print(result.metrics.totalLatencyMs)       // wall-clock time
print(result.metrics.outputTokensPerSecond)

// Token usage
print(result.usage.inputTokens)
print(result.usage.outputTokens)
print(result.usage.totalTokens)

// Per-cycle breakdown
for cycle in result.metrics.cycles {
    print("Cycle \(cycle.cycleNumber):")
    print("  Latency:     \(cycle.modelLatencyMs)ms")
    print("  Stop reason: \(cycle.stopReason)")
    print("  Tools run:   \(cycle.toolsExecuted)")
    print("  Output tokens: \(cycle.usage.outputTokens)")
}

// Before each model call
agent.hookRegistry.addCallback(BeforeInvocationEvent.self) { event in
    print("Sending \(event.messages.count) messages to model")
}

// After each model call
agent.hookRegistry.addCallback(AfterInvocationEvent.self) { event in
    print("Model responded in \(event.latencyMs)ms")
}

// After each tool execution
agent.hookRegistry.addCallback(AfterToolEvent.self) { event in
    print("Tool \(event.toolName): \(event.result.status)")
}

// At the end of every run (good for logging to a metrics system)
agent.hookRegistry.addCallback(MetricsEvent.self) { event in
    myMetrics.record(
        cycles: event.metrics.cycleCount,
        tokens: event.metrics.totalUsage.totalTokens,
        latency: event.metrics.totalLatencyMs
    )
}