From d3af6d35c7c6e67e5adfd15b21f0f93ad6baecea Mon Sep 17 00:00:00 2001 From: Janos Tolgyesi Date: Tue, 15 Jul 2025 17:58:47 +0200 Subject: [PATCH 1/2] docs(telemetry): Add usage examples for setup_console_exporter and setup_otlp_exporter arguments --- .../observability-evaluation/traces.md | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/observability-evaluation/traces.md b/docs/user-guide/observability-evaluation/traces.md index c8ff378c..11de2ba6 100644 --- a/docs/user-guide/observability-evaluation/traces.md +++ b/docs/user-guide/observability-evaluation/traces.md @@ -217,7 +217,7 @@ Strands traces include rich attributes that provide context for each operation: | `tool.status` | Execution status (success/error) | | `gen_ai.tool.name` | Name of the tool called | | `gen_ai.tool.call.id` | Unique identifier for the tool call | -| `gen_ai.operation.name` | Gen-AI operation name | +| `gen_ai.operation.name` | Gen-AI operation name | | `gen_ai.event.start_time` | When tool execution began | | `gen_ai.event.end_time` | When tool execution completed | | `gen_ai.choice` | Formatted tool result | @@ -281,10 +281,36 @@ For high-volume applications, you may want to implement sampling to reduce the v # Example: Sample 10% of traces os.environ["OTEL_TRACES_SAMPLER"] = "traceidratio" os.environ["OTEL_TRACES_SAMPLER_ARG"] = "0.5" +``` + +### Configuring the exporters from source code + +The `StrandsTelemetry().setup_console_exporter()` and `StrandsTelemetry().setup_otlp_exporter()` methods accept keyword arguments that are passed to OpenTelemetry's [`ConsoleSpanExporter`](https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.export.html#opentelemetry.sdk.trace.export.ConsoleSpanExporter) and [`OTLPSpanExporter`](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html#opentelemetry.exporter.otlp.proto.http.trace_exporter.OTLPSpanExporter) initializers, respectively. This allows you to save the log lines to a file or set up the OTLP endpoints from Python code: + +```python +from os import linesep +from strands.telemetry import StrandsTelemetry + +strands_telemetry = StrandsTelemetry() +# Save telemetry to a local file and configure the serialization format +logfile = open("my_log.jsonl", "wt") +strands_telemetry.setup_console_exporter( + out=logfile, + formatter=lambda span: span.to_json() + linesep, +) +# ... your agent-running code goes here ... +logfile.close() +# Configure OTLP endpoints programmatically +strands_telemetry.setup_otlp_exporter( + endpoint="http://collector.example.com:4318", + headers={"key1": "value1", "key2": "value2"}, +) ``` +For more information about the accepted arguments, refer to `ConsoleSpanExporter` and `OTLPSpanExporter` in the [OpenTelemetry API documentation](https://opentelemetry-python.readthedocs.io). + ### Custom Attribute Tracking You can add custom attributes to any span: From f64bfe046aed8ae3e9f30ada445615e51d9f82b9 Mon Sep 17 00:00:00 2001 From: Janos Tolgyesi Date: Tue, 22 Jul 2025 16:18:09 +0200 Subject: [PATCH 2/2] docs(telemetry) Change order of exporters config section --- .../observability-evaluation/traces.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/user-guide/observability-evaluation/traces.md b/docs/user-guide/observability-evaluation/traces.md index 05885a95..97bcc483 100644 --- a/docs/user-guide/observability-evaluation/traces.md +++ b/docs/user-guide/observability-evaluation/traces.md @@ -283,6 +283,26 @@ os.environ["OTEL_TRACES_SAMPLER"] = "traceidratio" os.environ["OTEL_TRACES_SAMPLER_ARG"] = "0.5" ``` +### Custom Attribute Tracking + +You can add custom attributes to any span: + +```python +agent = Agent( + system_prompt="You are a helpful assistant that provides concise responses.", + tools=[http_request, calculator], + trace_attributes={ + "session.id": "abc-1234", + "user.id": "user-email-example@domain.com", + "tags": [ + "Agent-SDK", + "Okatank-Project", + "Observability-Tags", + ] + }, +) +``` + ### Configuring the exporters from source code The `StrandsTelemetry().setup_console_exporter()` and `StrandsTelemetry().setup_otlp_exporter()` methods accept keyword arguments that are passed to OpenTelemetry's [`ConsoleSpanExporter`](https://opentelemetry-python.readthedocs.io/en/latest/sdk/trace.export.html#opentelemetry.sdk.trace.export.ConsoleSpanExporter) and [`OTLPSpanExporter`](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html#opentelemetry.exporter.otlp.proto.http.trace_exporter.OTLPSpanExporter) initializers, respectively. This allows you to save the log lines to a file or set up the OTLP endpoints from Python code: @@ -311,26 +331,6 @@ strands_telemetry.setup_otlp_exporter( For more information about the accepted arguments, refer to `ConsoleSpanExporter` and `OTLPSpanExporter` in the [OpenTelemetry API documentation](https://opentelemetry-python.readthedocs.io). -### Custom Attribute Tracking - -You can add custom attributes to any span: - -```python -agent = Agent( - system_prompt="You are a helpful assistant that provides concise responses.", - tools=[http_request, calculator], - trace_attributes={ - "session.id": "abc-1234", - "user.id": "user-email-example@domain.com", - "tags": [ - "Agent-SDK", - "Okatank-Project", - "Observability-Tags", - ] - }, -) -``` - ## Best Practices 1. **Use appropriate detail level**: Balance between capturing enough information and avoiding excessive data