> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt > Use this file to discover all available pages before exploring further. # Send Data with the Honeycomb Distribution for Python > Reference documentation for the Honeycomb Distribution for Python, a deprecated wrapper for the OpenTelemetry Python SDK. Migrate to the OpenTelemetry Python SDK instead. Honeycomb OpenTelemetry Distributions have reached [End of Life](/troubleshoot/product-lifecycle/release-stages/#end-of-life) and are now archived. * Adding new instrumentation? We recommend that you use the [OpenTelemetry for Python SDK](/send-data/python/opentelemetry-sdk/) instead. * Already using a Honeycomb distribution? We recommend that you [migrate to OpenTelemetry](/troubleshoot/product-lifecycle/recommended-migrations/migrate-from-honeycomb-distributions/). Honeycomb provides the [Honeycomb OpenTelemetry Distribution for Python](https://github.com/honeycombio/honeycomb-opentelemetry-python) to help you instrument your applications and send telemetry data to Honeycomb as quickly and easily as possible. Under the hood, the Honeycomb Distribution uses [OpenTelemetry for Python](/send-data/python/opentelemetry-sdk/), so advanced users or those who have already instrumented their applications with OpenTelemetry do not need to use this Distribution. The Honeycomb Distribution reads variables you provide and translates them to variables understood by the upstream OpenTelemetry SDK. For example, the Honeycomb Distribution automatically configures exporters to send telemetry data to Honeycomb's API (if you are using our US instance, `api.honeycomb.io`, or if you are using our EU instance, `api.eu1.honeycomb.io`). If you want to [send data to Honeycomb using OpenTelemetry without the Honeycomb Distribution](/send-data/python/opentelemetry-sdk/), you will need to configure your implementation to match variables expected by OpenTelemetry. In this guide, we explain how to set up automatic and custom, or manual, instrumentation for a service written in Python. If you prefer learning by example, we provide [several examples](https://github.com/honeycombio/honeycomb-opentelemetry-python/tree/main/examples/) of applications configured to send OpenTelemetry data to Honeycomb using the Honeycomb OpenTelemetry Distribution for Python. ## Before You Begin Before you can set up automatic instrumentation for your Python application, you will need to do a few things. ### Prepare Your Development Environment To complete the required steps, you will need: * A working Python environment with Python 3.7 or higher * An application written in Python ### Get Your Honeycomb API Key To send data to Honeycomb, you'll need to [sign up for a free Honeycomb account](https://ui.honeycomb.io/signup) and [create a Honeycomb Ingest API Key](/configure/environments/manage-api-keys/#create-api-key). To get started, you can create a key that you expect to swap out when you deploy to production. Name it something helpful, perhaps noting that it's a getting started key. Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later! For setup, make sure you check the "Can create datasets" checkbox so that your data will show up in Honeycomb. Later, when you replace this key with a permanent one, you can uncheck that box. If you want to use an API key you previously stored in a secure location, you can also [look up details for Honeycomb API Keys](/configure/environments/manage-api-keys/#find-api-keys) any time in your Environment Settings, and use them to retrieve keys from your storage location. ## Add Automatic Instrumentation Automatic instrumentation is provided by an agent, a command line tool `opentelemetry-instrument` that is used to run your application. Add additional instrumentation to your application manually using the included OpenTelemetry Python SDK. ### Acquire Dependencies Install Honeycomb and OpenTelemetry packages: 1. Install [Honeycomb's OpenTelemetry Python distribution package](https://pypi.org/project/honeycomb-opentelemetry/). ```shell theme={} python -m pip install honeycomb-opentelemetry --pre ``` 2. Install OpenTelemetry's automatic instrumentation libraries for the packages used by your Python application. We recommend that you use the `opentelemetry-bootstrap` tool that comes with the OpenTelemetry Python SDK to scan your application packages and generate the list of available libraries. By default, the tool prints out the instrumentation libraries that are available, which you can add to your `requirements.txt` file: ```shell theme={} opentelemetry-bootstrap >> requirements.txt pip install -r requirements.txt ``` If you do not use a `requirements.txt` file, you can install the libraries directly in your current environment: ```shell theme={} opentelemetry-bootstrap --action=install ``` Install packages: 1. Install [Honeycomb's OpenTelemetry Python distribution package](https://pypi.org/project/honeycomb-opentelemetry/). ```shell theme={} poetry add honeycomb-opentelemetry ``` 2. Install OpenTelemetry's automatic instrumentation libraries for the packages used by your Python application. We recommend that you use the `opentelemetry-bootstrap` tool that comes with the OpenTelemetry Python SDK to scan your application packages and generate a list of available libraries. ```shell theme={} poetry run opentelemetry-bootstrap ``` The tool does not support installing packages directly when using Poetry, so you must install them manually. For example, to install the Flask instrumentation library: ```shell theme={} poetry add opentelemetry-instrumentation-flask ``` ### Configure Use environment variables to configure the Honeycomb OpenTelemetry Python distribution package: ```shell theme={} export HONEYCOMB_API_ENDPOINT="api.honeycomb.io:443" # US instance #export HONEYCOMB_API_ENDPOINT="api.eu1.honeycomb.io:443" # EU instance export OTEL_SERVICE_NAME="your-service-name" export HONEYCOMB_API_KEY="your-api-key" ``` | Variable | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `HONEYCOMB_API_ENDPOINT` | Honeycomb endpoint to which you want to send your data. | | `OTEL_SERVICE_NAME` | Service name. When you send data, Honeycomb creates a dataset in which to store your data and uses this as the name. Can be any string. | | `HONEYCOMB_API_KEY` | Your API Key generated in Honeycomb. [Learn how to find your Honeycomb API Key](/configure/environments/manage-api-keys/#find-api-keys). | Use environment variables to configure the Honeycomb OpenTelemetry Python distribution package: ```shell theme={} export OTEL_SERVICE_NAME="your-service-name" export HONEYCOMB_API_KEY="your-api-key" ``` | Variable | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `OTEL_SERVICE_NAME` | Service name. When you send data, Honeycomb creates a dataset in which to store your data and uses this as the name. Can be any string. | | `HONEYCOMB_API_KEY` | Your API Key generated in Honeycomb. [Learn how to find your Honeycomb API Key](/configure/environments/manage-api-keys/#find-api-keys). | If you are a [Honeycomb Classic](/troubleshoot/product-lifecycle/recommended-migrations/#migrate-from-honeycomb-classic-to-honeycomb-environments) user, you must also specify the Dataset using the `HONEYCOMB_TRACES_DATASET` environment variable: ```shell theme={} export HONEYCOMB_TRACES_DATASET=my-traces ``` #### Advanced Configuration Explore all configuration options for the Honeycomb Distribution: | Environment Variable | Default Value | Description | | --------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `HONEYCOMB_API_KEY` | None | **\[required -- see note below]** Your Honeycomb API key | | `OTEL_SERVICE_NAME` | `unknown_service` | **\[required -- see note below]** `service.name` attribute, where all trace data is sent | | `HONEYCOMB_TRACES_APIKEY` | Value of `HONEYCOMB_API_KEY` | Your Honeycomb API key for sending traces | | `HONEYCOMB_METRICS_APIKEY` | Value of `HONEYCOMB_API_KEY` | Your Honeycomb API key for sending metrics | | `HONEYCOMB_METRICS_DATASET` | None | Honeycomb dataset where metrics will be sent | | `HONEYCOMB_API_ENDPOINT` | `api.honeycomb.io:443` (US instance)
`api.eu1.honeycomb.io:443` (EU instance) | Honeycomb ingest endpoint | | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Value of `HONEYCOMB_API_ENDPOINT` | Honeycomb ingest endpoint for traces (defaults to the value of `HONEYCOMB_API_ENDPOINT`) | | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Value of `HONEYCOMB_API_ENDPOINT` | Honeycomb ingest endpoint for metrics (defaults to the value of `HONEYCOMB_API_ENDPOINT`) | | `SAMPLE_RATE` | `1` (retain all data) | Sample rate for the deterministic sampler. Must be a positive integer. | | `HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS` | `false` | Enable [local visualizations](#visualizing-traces-locally) | | `DEBUG` | `false` | Enable debug mode | If you are sending data directly to Honeycomb, you must configure the API key and service name. If you are using an [OpenTelemetry Collector](/send-data/opentelemetry/collector/), configure your API key at the Collector level instead. ### Run Run your Python application using the OpenTelemetry Python automatic instrumentation tool `opentelemetry-instrument`, which configures the OpenTelemetry SDK: ```shell theme={} opentelemetry-instrument python YOUR_APPLICATION_NAME.py ``` Be sure to replace `YOUR_APPLICATION_NAME` with the name of your application's main file. In Honeycomb's UI, you should now see your application's incoming requests and outgoing HTTP calls generate traces. Run your Python application using the OpenTelemetry Python automatic instrumentation tool `opentelemetry-instrument`, which configures the OpenTelemetry SDK: ```shell theme={} poetry run opentelemetry-instrument python YOUR_APPLICATION_NAME.py ``` Be sure to replace `YOUR_APPLICATION_NAME` with the name of your application's main file. In Honeycomb's UI, you should now see your application's incoming requests and outgoing HTTP calls generate traces. ## Add Custom Instrumentation Automatic instrumentation is the easiest way to get started with instrumenting your code. To get additional insight into your system, you should also add custom, or manual, instrumentation where appropriate. To learn more about custom, or manual, instrumentation, visit the comprehensive set of topics covered by [Manual Instrumentation for Python](https://opentelemetry.io/docs/languages/python/instrumentation/) in OpenTelemetry's documentation. ### Acquire Dependencies To start adding custom instrumentation, ensure that the `opentelemetry-api` package exists as a direct dependency in your project. This package provides access to the high-level instrumentation APIs, which gives the ability to retrieve the current span to enrich with additional attributes, to create new spans, and to generate metrics. ```shell pip theme={} python -m pip install opentelemetry-api ``` ```shell poetry theme={} poetry add opentelemetry-api ``` ### Add Attributes to Spans Adding context to a currently executing span in a trace can be useful. For example, you may have an application or service that handles users, and you want to associate the user with the span when querying your dataset in Honeycomb. To do this, get the current span from the context and set an attribute with the user ID: ```python theme={} from opentelemetry import trace # ... span = trace.get_current_span() span.set_attribute("user.id", user.id()) ``` ### Acquire a Tracer To create spans, you need to acquire a `Tracer`. ```python theme={} from opentelemetry import trace tracer = trace.get_tracer("tracer.name.here") ``` When you create a `Tracer`, OpenTelemetry requires you to give it a name as a string. This string is the only required parameter. When traces are sent to Honeycomb, the name of the `Tracer` is turned into the `library.name` field, which can be used to show all spans created from a particular tracer. In general, pick a name that matches the appropriate scope for your traces. If you have one tracer for each service, then use the service name. If you have multiple tracers that live in different "layers" of your application, then use the name that corresponds to that "layer". The `library.name` field is also used with traces created from instrumentation libraries. ### Create Spans Automatic instrumentation can show the shape of requests to your system, but only you know the really important parts. To get the full picture of what's happening, you should add custom instrumentation and create some custom spans. To do this, create or re-use a `Tracer` instance and start a span. ```python theme={} from opentelemetry import trace tracer = trace.get_tracer("tracer.name.here") with tracer.start_as_current_span("some-long-running-handler"): # prepare to auth with tracer.start_as_current_span("what-it-takes-to-authorize-handling"): # do the auth # do the authorized long running handling of cool stuff ``` #### Creating Spans Around Methods You can use a decorator to wrap the execution of a method with a span. The span will be automatically closed once the method has completed. ```python theme={} from opentelemetry import trace tracer = trace.get_tracer("tracer.name.here") # ... @tracer.start_as_current_span("do_work") def do_work(): # do some work ... ``` ### Add Multi-Span Attributes Sometimes you want to add the same attribute to many spans within the same trace. This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes. To add this attribute, leverage the OpenTelemetry concept of [baggage](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#baggage-signal). Baggage allows you to add a `key` with a `value` as an attribute to every subsequent child span of the current application context. In Python, baggage is configured as part of the OpenTelemetry trace context. Modifications to the trace context must be both attached and detached when no longer used to make sure context state is disposed of correctly. The following example adds a user ID attribute to multiple spans in a trace. ```python theme={} from opentelemetry import baggage from opentelemetry.context import attach, detach ... token = attach( baggage.set_baggage("user.id", user.id()) ) with tracer.start_as_current_span(name="hello"): span.set_attribute("message", "hello world!") detach(token) ``` If you do not detach a modified trace context, you will see runtime errors as the OpenTelemetry SDK will detect un-detached contexts in its internal stack. Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do **NOT** put sensitive information in the Baggage attributes. ## Sampling To control how many spans are being sent to Honeycomb, you can configure the OpenTelemetry SDK to [sample the data](/manage-data-volume/sample/guidelines/) it generates. You can configure sampling with environment variables. The following example sets a sample rate of 2, meaning 50% of traces are sampled and sent to Honeycomb: ```shell theme={} export SAMPLE_RATE="2" ``` If you have multiple services that communicate with each other, it is important that they have the same sampling configuration. Otherwise, each service might make a different sampling decision, resulting in incomplete or broken traces. You can sample using a standalone proxy as an alternative, like [Honeycomb Refinery](/manage-data-volume/sample/honeycomb-refinery/), or when you have more robust sampling needs. ## Distributed Trace Propagation When a service calls another service, you want to ensure that the relevant trace information is propagated from one service to the other. This allows Honeycomb to connect the two services in a trace. Distributed tracing enables you to trace and visualize interactions between multiple instrumented services. For example, your users may interact with a front-end API service, which talks to two internal APIs to fulfill their request. In order to have traces connect spans for all these services, it is necessary to propagate trace context between these services, usually by using an HTTP header. Both the sending and receiving service must use the same propagation format, and both services must be configured to send data to the same Honeycomb environment. ## Visualizing Traces Locally Honeycomb's OpenTelemetry Distribution for Python can create a link to a trace visualization in the Honeycomb UI for local traces. Local visualizations enable a faster feedback cycle when adding, modifying, or verifying instrumentation. To enable local visualizations: 1. Set the `HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS` environment variable to `true`: ```shell theme={} export HONEYCOMB_ENABLE_LOCAL_VISUALIZATIONS=true ``` 2. Run your application: ```shell theme={} opentelemetry-instrument python myapp.py ``` The output displays the name of the root span and a link to Honeycomb that shows its trace. For example: ```text theme={} Trace for Honeycomb link: ``` 3. Select the link to view the trace in detail within the Honeycomb UI. In production, disable local visualization. Local visualization creates additional overhead to create the link to a trace in Honeycomb and print it to the console. ## Using HTTP/protobuf instead of gRPC By default, the Honeycomb OpenTelemetry SDK uses the gRPC protocol to send telemetry data. To use HTTP instead of gRPC, set the export protocol for the OpenTelemetry SDK using the following environment variable: ```shell theme={} export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` If using the signal-specific `OTEL_EXPORTER_OTLP__ENDPOINT` environment variable, you must append the endpoint with the appropriate signal path. For example, if sending traces, append the endpoint with `v1/traces`. If sending metrics, append the endpoint with `v1/metrics`. ## Troubleshooting To explore common issues when sending data, visit [Common Issues with Sending Data in Honeycomb](/troubleshoot/common-issues/sending-data/#opentelemetry-sdks-and-honeycomb-distributions).