Send OpenTelemetry from FastAPI to your Mac

Python needs no code change. The OpenTelemetry distro wraps the process and instruments FastAPI, the HTTP client, and the database driver it finds.

Before you start

• Loggerhead is open.
• You know the effective port. Open Collectors → Loggerhead receiver → Connection and copy the HTTP port. The first workspace uses 4318. See Ports and the effective port.

Step 1: install

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap reads the packages you already have and installs the matching instrumentation.

Step 2: set the endpoint

.env

OTEL_SERVICE_NAME=my-api
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_LOGS_EXPORTER=otlp
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_SEMCONV_STABILITY_OPT_IN=http,database

The two LOGS lines send your logging records as well. Without them Python sends traces and metrics only. The last line asks the instrumentation for the current attribute names, such as http.request.method and db.query.text. Without it the spans carry the names that OpenTelemetry renamed, and the lint rule “Renamed attribute keys” reports them.

Step 3: start the app

opentelemetry-instrument uvicorn main:app --reload

Call one endpoint, then open Traces in Loggerhead.

What arrives

Signal	State
Traces	Every request, and the calls the instrumentation finds inside it.
Metrics	Request duration and count, plus the runtime metrics.
Logs	Every logging record, with its trace ID, when the two log settings are on.

Tag the environment

OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=staging

See Workspaces and environments.

Then read it with your agent

1. Open Logs in Loggerhead. Click a log line, then click its trace ID in the detail to open the trace.
2. Connect your coding agent once, and it reads the same data. See Claude Code.