Skip to content

feat(telemetry): support gRPC transport for OTLP exporters#2325

Open
aribault wants to merge 2 commits into
strands-agents:mainfrom
aribault:feat/telemetry-otlp-grpc-exporter
Open

feat(telemetry): support gRPC transport for OTLP exporters#2325
aribault wants to merge 2 commits into
strands-agents:mainfrom
aribault:feat/telemetry-otlp-grpc-exporter

Conversation

@aribault
Copy link
Copy Markdown

Motivation

StrandsTelemetry.setup_otlp_exporter and the OTLP-metrics path inside setup_meter hard-code the HTTP variant of OTLPSpanExporter / OTLPMetricExporter. Users running their telemetry through the OpenTelemetry Collector (or vendor agents that prefer gRPC) currently have to bypass the helpers entirely and reconstruct the providers themselves.

This change adds first-class gRPC support while keeping HTTP as the default, matching Unshure's direction in #689.

Resolves: #689

Note: This PR is stacked on #2324 (issue #843). Until that lands on main, the GitHub diff here will include #2324's setup_meter provider_kwargs commit. Once #2324 merges, this branch will rebase onto fresh main and the diff will collapse to just the gRPC-related changes.

Public API Changes

setup_otlp_exporter now accepts a protocol parameter, and setup_meter accepts otlp_protocol. Resolution order is explicit arg → OTEL_EXPORTER_OTLP_PROTOCOL env var → http/protobuf (matching the OTel SDK convention). When \"grpc\" is selected and the optional dependency is missing, an ImportError surfaces a pip install hint pointing at the new otel-grpc extra.

# Before — no way to choose gRPC short of bypassing setup_otlp_exporter entirely
StrandsTelemetry().setup_otlp_exporter(endpoint=\"https://collector:4318/v1/traces\")

# After — explicit protocol selection
StrandsTelemetry().setup_otlp_exporter(
    protocol=\"grpc\",
    endpoint=\"https://collector:4317\",
)

# Or via the standard OTel env var
# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
StrandsTelemetry().setup_otlp_exporter()  # picks up env

# Same shape on the metrics side
StrandsTelemetry().setup_meter(enable_otlp_exporter=True, otlp_protocol=\"grpc\")

New Optional Dependency

A new otel-grpc extra in pyproject.toml:

otel-grpc = [\"opentelemetry-exporter-otlp-proto-grpc>=1.30.0,<2.0.0\"]

The existing otel extra is untouched (HTTP-only). Users opt into gRPC explicitly via pip install 'strands-agents[otel-grpc]'. The all meta-extra now includes otel-grpc so users on [all] get both transports.

Existing callers (no protocol argument, otel extra installed) keep their previous behavior with no install-size growth.

aribault added 2 commits May 25, 2026 22:14
setup_meter previously hard-coded the MeterProvider construction to only
accept resource and metric_readers, forcing users who needed views,
exemplar_filter, or shutdown_on_exit to bypass the helper entirely and
reconstruct the provider from scratch. This change accepts arbitrary
keyword arguments and forwards them, exposing the full MeterProvider
surface without changing existing behavior.

Resolves: strands-agents#843
setup_otlp_exporter and setup_meter previously hard-coded the HTTP variant
of OTLPSpanExporter and OTLPMetricExporter, leaving users who need gRPC
(common with OpenTelemetry Collector and several vendor agents) no choice
but to bypass the helpers and reconstruct the providers manually.

Both methods now accept a protocol parameter ("http/protobuf" or "grpc"),
falling back to the standard OTEL_EXPORTER_OTLP_PROTOCOL env var, then to
http/protobuf. The gRPC dependency lives in a new opt-in 'otel-grpc' extra
so existing 'otel' installs are unchanged in size and behavior.

Resolves: strands-agents#689
@aribault aribault marked this pull request as ready for review May 25, 2026 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Support GRPC OTLP exporter

1 participant