# Instrumenting a Python Service — Logging, Metrics, Tracing & Alerting

Source: https://www.skillbyai.com/en/observability/ob-otel-python

> Add OpenTelemetry tracing to a Python app with auto-instrumentation and with manual spans for business logic.

## Automatic first, manual where it matters

**Automatic instrumentation** wraps well-known libraries at startup: incoming HTTP requests become `SERVER` spans, outgoing HTTP and database calls become `CLIENT` spans, and context propagation headers are injected and extracted for you. In Python this is the `opentelemetry-instrument` launcher; Java uses a `-javaagent` JAR; Node.js loads an SDK setup file before the app. Configuration is mostly environment variables such as `OTEL_SERVICE_NAME` and `OTEL_EXPORTER_OTLP_ENDPOINT`.

Auto-instrumentation shows *where* time goes between components but knows nothing about your business. **Manual instrumentation** adds spans around meaningful operations (pricing a cart, charging a card) and attributes that matter for debugging (order ID, payment method, cart size). You get a tracer from the global provider, open a span with a context manager, and set attributes, events and status.

Keep span names **low-cardinality** (`payments.charge`, not `charge order A17`) and put IDs in attributes. Span names are used to group and aggregate, much like metric names.

## Manual spans with the Python SDK

Needs `pip install opentelemetry-sdk`. The nested `with` blocks make `payments.charge` a child of `POST /checkout`. The console exporter prints each finished span as JSON; in production you would swap it for an OTLP exporter.

```python
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.trace import Status, StatusCode

provider = TracerProvider(resource=Resource.create({"service.name": "checkout"}))
provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

def charge(order_id: str, amount: int) -> None:
    with tracer.start_as_current_span("payments.charge") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("payment.amount_inr", amount)
        if amount > 10_000:
            span.set_status(Status(StatusCode.ERROR, "limit exceeded"))
            return
        span.add_event("charge accepted")

with tracer.start_as_current_span("POST /checkout"):
    charge("A17", 499)

provider.shutdown()   # flush buffered spans before the process exits
```

## Zero-code instrumentation

The launcher installs instrumentations, reads configuration from environment variables and starts your app. The sampler shown keeps 10% of new traces but follows the parent's decision for traces started upstream.

```bash
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install     # adds instrumentations for libraries it detects

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=prod
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

opentelemetry-instrument python app.py
```

## Always shut down or flush

Batch processors hold spans in memory and export them every few seconds. A short script or a serverless function that exits immediately can lose its last batch. Call `provider.shutdown()` or `force_flush()` before exit; long-running servers normally do this through the SDK's shutdown hooks.

**Quiz:** Which span name follows OpenTelemetry guidance best?

- [ ] charge order A17 for 499 rupees
- [x] payments.charge, with the order ID stored as an attribute
- [ ] span-1
- [ ] a new random UUID per request

*Answer:* payments.charge, with the order ID stored as an attribute. Span names should be low-cardinality so spans can be grouped. Variable details like the order ID belong in attributes.
