# OTLP Stdout Span Exporter for Python
A Python span exporter that writes OpenTelemetry spans to stdout, using a custom serialization format that embeds the spans serialized as OTLP protobuf in the `payload` field. The message envelope carries metadata about the spans, such as the service name, the OTLP endpoint, and the HTTP method:
```json
{
"__otel_otlp_stdout": "0.1.0",
"source": "my-service",
"endpoint": "http://localhost:4318/v1/traces",
"method": "POST",
"content-type": "application/x-protobuf",
"content-encoding": "gzip",
"headers": {
"tenant-id": "tenant-12345",
"custom-header": "value"
},
"payload": "<base64-encoded-gzipped-protobuf>",
"base64": true
}
```
Outputting telemetry data in this format directly to stdout makes the library easily usable in network constrained environments, or in environments that are particularly sensitive to the overhead of HTTP connections, such as AWS Lambda.
>[!IMPORTANT]
>This package is part of the [serverless-otlp-forwarder](https://github.com/dev7a/serverless-otlp-forwarder) project and is designed for AWS Lambda environments. While it can be used in other contexts, it's primarily tested with AWS Lambda.
## Features
- Uses OTLP Protobuf serialization for efficient encoding
- Applies GZIP compression with configurable levels
- Detects service name from environment variables
- Supports custom headers via environment variables
- Consistent JSON output format
- Zero external HTTP dependencies
- Lightweight and fast
## Installation
```bash
pip install otlp-stdout-span-exporter
```
## Usage
The recommended way to use this exporter is with the standard OpenTelemetry `BatchSpanProcessor`, which provides better performance by buffering and exporting spans in batches, or, in conjunction with the [lambda-otel-lite](https://pypi.org/project/lambda-otel-lite/) package, with the `LambdaSpanProcessor`, which is particularly optimized for AWS Lambda.
You can create a simple tracer provider with the BatchSpanProcessor and the OTLPStdoutSpanExporter:
```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from otlp_stdout_span_exporter import OTLPStdoutSpanExporter
# Create and set the tracer provider
provider = TracerProvider()
trace.set_tracer_provider(provider)
# Create and register the exporter with optional GZIP compression level
exporter = OTLPStdoutSpanExporter(gzip_level=6)
provider.add_span_processor(BatchSpanProcessor(exporter))
# Your instrumentation code here
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("my-operation") as span:
span.set_attribute("my.attribute", "value")
```
## Configuration
### Constructor Options
```python
OTLPStdoutSpanExporter(
# GZIP compression level (0-9, where 0 is no compression and 9 is maximum compression)
# Defaults to 6 or value from OTLP_STDOUT_SPAN_EXPORTER_COMPRESSION_LEVEL
gzip_level=9
)
```
The explicit configuration via code will override any environment variable setting.
### Environment Variables
The exporter respects the following environment variables:
- `OTEL_SERVICE_NAME`: Service name to use in output
- `AWS_LAMBDA_FUNCTION_NAME`: Fallback service name (if `OTEL_SERVICE_NAME` not set)
- `OTEL_EXPORTER_OTLP_HEADERS`: Headers for OTLP export, used in the `headers` field
- `OTEL_EXPORTER_OTLP_TRACES_HEADERS`: Trace-specific headers (which take precedence if conflicting with `OTEL_EXPORTER_OTLP_HEADERS`)
- `OTLP_STDOUT_SPAN_EXPORTER_COMPRESSION_LEVEL`: GZIP compression level (0-9). Defaults to 6.
>[!NOTE]
>For security best practices, avoid including authentication credentials or sensitive information in headers. The serverless-otlp-forwarder infrastructure is designed to handle authentication at the destination, rather than embedding credentials in your telemetry data.
## Output Format
The exporter writes JSON objects to stdout with the following structure:
```json
{
"__otel_otlp_stdout": "0.1.0",
"source": "my-service",
"endpoint": "http://localhost:4318/v1/traces",
"method": "POST",
"content-type": "application/x-protobuf",
"content-encoding": "gzip",
"headers": {
"tenant-id": "tenant-12345",
"custom-header": "value"
},
"base64": true,
"payload": "<base64-encoded-gzipped-protobuf>"
}
```
- `__otel_otlp_stdout` is a marker to identify the output of this exporter.
- `source` is the emittingservice name.
- `endpoint` is the OTLP endpoint (defaults to `http://localhost:4318/v1/traces` and just indicates the signal type. The actual endpoint is determined by the process that forwards the data).
- `method` is the HTTP method (always `POST`).
- `content-type` is the content type (always `application/x-protobuf`).
- `content-encoding` is the content encoding (always `gzip`).
- `headers` is the headers defined in the `OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_EXPORTER_OTLP_TRACES_HEADERS` environment variables.
- `payload` is the base64-encoded, gzipped, Protobuf-serialized span data in OTLP format.
- `base64` is a boolean flag to indicate if the payload is base64-encoded (always `true`).
## License
MIT
## See Also
- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder) - The main project repository for the Serverless OTLP Forwarder project
- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder/tree/main/packages/node/otlp-stdout-span-exporter) | [npm](https://www.npmjs.com/package/@dev7a/otlp-stdout-span-exporter) - The Node.js version of this exporter
- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder/tree/main/packages/rust/otlp-stdout-span-exporter) | [crates.io](https://crates.io/crates/otlp-stdout-span-exporter) - The Rust version of this exporter
Raw data
{
"_id": null,
"home_page": null,
"name": "otlp-stdout-span-exporter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "exporter, opentelemetry, otlp, spans, stdout, tracing",
"author": null,
"author_email": "Alessandro Bologna <alessandro.bologna@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fb/73/3572bac7c6c0f3ed825c417e68d07a70a2b4890b712854a3f5d623f96e87/otlp_stdout_span_exporter-0.10.0.tar.gz",
"platform": null,
"description": "# OTLP Stdout Span Exporter for Python\n\nA Python span exporter that writes OpenTelemetry spans to stdout, using a custom serialization format that embeds the spans serialized as OTLP protobuf in the `payload` field. The message envelope carries metadata about the spans, such as the service name, the OTLP endpoint, and the HTTP method:\n\n```json\n{\n \"__otel_otlp_stdout\": \"0.1.0\",\n \"source\": \"my-service\",\n \"endpoint\": \"http://localhost:4318/v1/traces\",\n \"method\": \"POST\",\n \"content-type\": \"application/x-protobuf\",\n \"content-encoding\": \"gzip\",\n \"headers\": {\n \"tenant-id\": \"tenant-12345\",\n \"custom-header\": \"value\"\n },\n \"payload\": \"<base64-encoded-gzipped-protobuf>\",\n \"base64\": true\n}\n```\n\nOutputting telemetry data in this format directly to stdout makes the library easily usable in network constrained environments, or in environments that are particularly sensitive to the overhead of HTTP connections, such as AWS Lambda.\n\n>[!IMPORTANT]\n>This package is part of the [serverless-otlp-forwarder](https://github.com/dev7a/serverless-otlp-forwarder) project and is designed for AWS Lambda environments. While it can be used in other contexts, it's primarily tested with AWS Lambda.\n\n## Features\n\n- Uses OTLP Protobuf serialization for efficient encoding\n- Applies GZIP compression with configurable levels\n- Detects service name from environment variables\n- Supports custom headers via environment variables\n- Consistent JSON output format\n- Zero external HTTP dependencies\n- Lightweight and fast\n\n## Installation\n\n```bash\npip install otlp-stdout-span-exporter\n```\n\n## Usage\n\nThe recommended way to use this exporter is with the standard OpenTelemetry `BatchSpanProcessor`, which provides better performance by buffering and exporting spans in batches, or, in conjunction with the [lambda-otel-lite](https://pypi.org/project/lambda-otel-lite/) package, with the `LambdaSpanProcessor`, which is particularly optimized for AWS Lambda.\n\nYou can create a simple tracer provider with the BatchSpanProcessor and the OTLPStdoutSpanExporter:\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom otlp_stdout_span_exporter import OTLPStdoutSpanExporter\n\n# Create and set the tracer provider\nprovider = TracerProvider()\ntrace.set_tracer_provider(provider)\n\n# Create and register the exporter with optional GZIP compression level\nexporter = OTLPStdoutSpanExporter(gzip_level=6)\nprovider.add_span_processor(BatchSpanProcessor(exporter))\n\n# Your instrumentation code here\ntracer = trace.get_tracer(__name__)\nwith tracer.start_as_current_span(\"my-operation\") as span:\n span.set_attribute(\"my.attribute\", \"value\")\n```\n\n\n## Configuration\n\n### Constructor Options\n\n```python\nOTLPStdoutSpanExporter(\n # GZIP compression level (0-9, where 0 is no compression and 9 is maximum compression)\n # Defaults to 6 or value from OTLP_STDOUT_SPAN_EXPORTER_COMPRESSION_LEVEL\n gzip_level=9\n)\n```\nThe explicit configuration via code will override any environment variable setting.\n\n### Environment Variables\n\nThe exporter respects the following environment variables:\n\n- `OTEL_SERVICE_NAME`: Service name to use in output\n- `AWS_LAMBDA_FUNCTION_NAME`: Fallback service name (if `OTEL_SERVICE_NAME` not set)\n- `OTEL_EXPORTER_OTLP_HEADERS`: Headers for OTLP export, used in the `headers` field\n- `OTEL_EXPORTER_OTLP_TRACES_HEADERS`: Trace-specific headers (which take precedence if conflicting with `OTEL_EXPORTER_OTLP_HEADERS`)\n- `OTLP_STDOUT_SPAN_EXPORTER_COMPRESSION_LEVEL`: GZIP compression level (0-9). Defaults to 6.\n\n>[!NOTE]\n>For security best practices, avoid including authentication credentials or sensitive information in headers. The serverless-otlp-forwarder infrastructure is designed to handle authentication at the destination, rather than embedding credentials in your telemetry data.\n\n\n## Output Format\n\nThe exporter writes JSON objects to stdout with the following structure:\n\n```json\n{\n \"__otel_otlp_stdout\": \"0.1.0\",\n \"source\": \"my-service\",\n \"endpoint\": \"http://localhost:4318/v1/traces\",\n \"method\": \"POST\",\n \"content-type\": \"application/x-protobuf\",\n \"content-encoding\": \"gzip\",\n \"headers\": {\n \"tenant-id\": \"tenant-12345\",\n \"custom-header\": \"value\"\n },\n \"base64\": true,\n \"payload\": \"<base64-encoded-gzipped-protobuf>\"\n}\n```\n\n- `__otel_otlp_stdout` is a marker to identify the output of this exporter.\n- `source` is the emittingservice name.\n- `endpoint` is the OTLP endpoint (defaults to `http://localhost:4318/v1/traces` and just indicates the signal type. The actual endpoint is determined by the process that forwards the data).\n- `method` is the HTTP method (always `POST`).\n- `content-type` is the content type (always `application/x-protobuf`).\n- `content-encoding` is the content encoding (always `gzip`).\n- `headers` is the headers defined in the `OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_EXPORTER_OTLP_TRACES_HEADERS` environment variables.\n- `payload` is the base64-encoded, gzipped, Protobuf-serialized span data in OTLP format.\n- `base64` is a boolean flag to indicate if the payload is base64-encoded (always `true`).\n\n\n## License\n\nMIT\n\n## See Also\n\n- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder) - The main project repository for the Serverless OTLP Forwarder project\n- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder/tree/main/packages/node/otlp-stdout-span-exporter) | [npm](https://www.npmjs.com/package/@dev7a/otlp-stdout-span-exporter) - The Node.js version of this exporter\n- [GitHub](https://github.com/dev7a/serverless-otlp-forwarder/tree/main/packages/rust/otlp-stdout-span-exporter) | [crates.io](https://crates.io/crates/otlp-stdout-span-exporter) - The Rust version of this exporter\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "OpenTelemetry span exporter that writes to stdout in OTLP format",
"version": "0.10.0",
"project_urls": {
"homepage": "https://github.com/dev7a/serverless-otlp-forwarder/",
"repository": "https://github.com/dev7a/serverless-otlp-forwarder/tree/main/packages/python/otlp-stdout-span-exporter"
},
"split_keywords": [
"exporter",
" opentelemetry",
" otlp",
" spans",
" stdout",
" tracing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fbcd3513610fe6d7216485600255a0900e5bfd92036231d9e2a5e4c589596bd4",
"md5": "50e604833605229310d79ca412b67f1a",
"sha256": "0df77a961221fd50df3bef4db8ec29d61e2c915153d321e064888a7c29c64303"
},
"downloads": -1,
"filename": "otlp_stdout_span_exporter-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50e604833605229310d79ca412b67f1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 6682,
"upload_time": "2025-03-06T00:41:36",
"upload_time_iso_8601": "2025-03-06T00:41:36.122177Z",
"url": "https://files.pythonhosted.org/packages/fb/cd/3513610fe6d7216485600255a0900e5bfd92036231d9e2a5e4c589596bd4/otlp_stdout_span_exporter-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fb733572bac7c6c0f3ed825c417e68d07a70a2b4890b712854a3f5d623f96e87",
"md5": "d5781ef0a0e213140bd96dcfc54e67f8",
"sha256": "95adcf2ac3c22d76786c13a172ddd07d9b4de38e6d02a7ba82519ddfd60ef2e2"
},
"downloads": -1,
"filename": "otlp_stdout_span_exporter-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "d5781ef0a0e213140bd96dcfc54e67f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 6012,
"upload_time": "2025-03-06T00:41:37",
"upload_time_iso_8601": "2025-03-06T00:41:37.655264Z",
"url": "https://files.pythonhosted.org/packages/fb/73/3572bac7c6c0f3ed825c417e68d07a70a2b4890b712854a3f5d623f96e87/otlp_stdout_span_exporter-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-06 00:41:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dev7a",
"github_project": "serverless-otlp-forwarder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "otlp-stdout-span-exporter"
}
JSON
