otel-file-exporter 0.1.1

Lightweight OpenTelemetry file exporter that writes traces, logs and metrics to local JSON Lines files

otel_file_exporter

A lightweight OpenTelemetry file exporter that writes traces, logs and metrics to local JSON Lines files – no external back-ends required.
All traces, logs and metrics are written locally as newline-delimited JSON (*.jsonl) so they can be inspected with your favorite tools or fed into pipelines later.

telemetry/
├─ traces.jsonl   <- Spans
├─ logs.jsonl     <- Structured application logs
└─ metrics.jsonl  <- OTLP metrics exports

Why?

• Zero-dependency observability for demos, local development and CI
• Uses the official OpenTelemetry SDK – switch to OTLP / Jaeger / etc. at any time
• Demonstrates structured logging and custom OpenTelemetry exporters

Requirements

• Python 3.13 or newer (matches pyproject.toml)
• Windows, macOS or Linux – no native deps

Quick start

python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
python examples\fastapi_app.py

Then open http://localhost:8000/docs for the interactive Swagger UI.

Example requests

curl http://localhost:8000/health
curl http://localhost:8000/items/123?include_description=true

Watch the telemetry directory fill with JSONL lines while you interact with the API.

Environment variables

Var	Default	Purpose
SERVICE_NAME	fastapi-otel-demo	Resource attribute in traces/logs/metrics
SERVICE_VERSION	1.0.0	Resource attribute
ENVIRONMENT	development	Resource attribute
LOG_LEVEL	INFO	Console & JSONL log level
TRACE_SAMPLE_RATE	1.0	0.0-1.0 probability sampler
METRICS_EXPORT_INTERVAL	5000	Export interval in ms
OUTPUT_DIR	./telemetry	Where JSONL files are written
PORT	8000	HTTP port for the demo app

Set them in the shell, a .env file or your container orchestrator.

Library usage

Import the pre-configured helpers in your own code:

from otel_file_exporter import tracer, logger, app_metrics

with tracer.start_as_current_span("my_work"):
    logger.info("Hello with trace context!")

Project layout

examples/
└─ fastapi_app.py   # Self-contained demo API
src/otel_file_exporter/
    ├─ __init__.py
    └─ otel.py      # Custom exporters & bootstrap helpers
pyproject.toml
README.md

Development

pip install -e ".[dev]"   # add your own dev dependencies extras
pytest -q                 # add tests as you go

Feel free to open issues or PRs – contributions are welcome!

Publishing to PyPI

1. Trusted publishing (recommended)

The workflow in .github/workflows/release.yml uses PyPI’s Trusted Publishing (OIDC) together with
pypa/gh-action-pypi-publish@release/v1.

1. Enable “Trusted Publishing” for the project on PyPI and link it to this repository.
2. Create a GitHub Release (or press Run workflow in the Actions tab).
   The build artifacts are uploaded and automatically published to PyPI – no secret required.

2. Classic API-token publishing

The fallback workflow in .github/workflows/publish.yml is triggered whenever you push a git tag that matches v*.*.*.

1. Create a scoped PyPI API token with publish privileges.
2. Add it to the repository secrets as PYPI_API_TOKEN.
3. Tag and push a new version:

git tag v0.2.0
git push --tags

License

This project is licensed under the MIT License. See LICENSE for details.