# 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
```bash
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
```bash
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:
```python
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
```bash
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:
```cmd
git tag v0.2.0
git push --tags
```
## License
This project is licensed under the **MIT License**. See `LICENSE` for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "otel-file-exporter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "opentelemetry, tracing, logging, metrics, jsonl, observability",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/60/2be79dab0929ed620160530df0e81d2904f47c2890f1ff8855ae3bdbc1ec/otel_file_exporter-0.1.1.tar.gz",
"platform": null,
"description": "# otel_file_exporter\n\nA lightweight OpenTelemetry file exporter that writes traces, logs and metrics to local JSON Lines files \u2013 **no external back-ends required**. \nAll traces, logs and metrics are written locally as _newline-delimited JSON_ (`*.jsonl`) so they can be inspected with\nyour favorite tools or fed into pipelines later.\n\n```\ntelemetry/\n\u251c\u2500 traces.jsonl <- Spans\n\u251c\u2500 logs.jsonl <- Structured application logs\n\u2514\u2500 metrics.jsonl <- OTLP metrics exports\n```\n\n## Why?\n\n* Zero-dependency observability for demos, local development and CI\n* Uses the official OpenTelemetry SDK \u2013 switch to OTLP / Jaeger / etc. at any time\n* Demonstrates **structured logging** and **custom OpenTelemetry exporters**\n\n## Requirements\n\n* Python **3.13** or newer (matches `pyproject.toml`)\n* Windows, macOS or Linux \u2013 no native deps\n\n## Quick start\n\n```bash\npython -m venv .venv\n.\\.venv\\Scripts\\activate\npip install -e .\npython examples\\fastapi_app.py\n```\n\nThen open `http://localhost:8000/docs` for the interactive Swagger UI.\n\n## Example requests\n\n```bash\ncurl http://localhost:8000/health\ncurl http://localhost:8000/items/123?include_description=true\n```\n\nWatch the `telemetry` directory fill with JSONL lines while you interact with the API.\n\n## Environment variables\n\n| Var | Default | Purpose |\n|-------------------------|--------------------|--------------------------------------------|\n| `SERVICE_NAME` | `fastapi-otel-demo`| Resource attribute in traces/logs/metrics |\n| `SERVICE_VERSION` | `1.0.0` | Resource attribute |\n| `ENVIRONMENT` | `development` | Resource attribute |\n| `LOG_LEVEL` | `INFO` | Console & JSONL log level |\n| `TRACE_SAMPLE_RATE` | `1.0` | 0.0-1.0 probability sampler |\n| `METRICS_EXPORT_INTERVAL`| `5000` | Export interval in **ms** |\n| `OUTPUT_DIR` | `./telemetry` | Where JSONL files are written |\n| `PORT` | `8000` | HTTP port for the demo app |\n\nSet them in the shell, a `.env` file or your container orchestrator.\n\n## Library usage\n\nImport the pre-configured helpers in your own code:\n\n```python\nfrom otel_file_exporter import tracer, logger, app_metrics\n\nwith tracer.start_as_current_span(\"my_work\"):\n logger.info(\"Hello with trace context!\")\n```\n\n## Project layout\n\n```\nexamples/\n\u2514\u2500 fastapi_app.py # Self-contained demo API\nsrc/otel_file_exporter/\n \u251c\u2500 __init__.py\n \u2514\u2500 otel.py # Custom exporters & bootstrap helpers\npyproject.toml\nREADME.md\n```\n\n## Development\n\n```bash\npip install -e \".[dev]\" # add your own dev dependencies extras\npytest -q # add tests as you go\n```\n\nFeel free to open issues or PRs \u2013 contributions are welcome!\n\n## Publishing to PyPI\n\n### 1. Trusted publishing (recommended)\n\nThe workflow in `.github/workflows/release.yml` uses PyPI\u2019s **Trusted Publishing** (OIDC) together with \n`pypa/gh-action-pypi-publish@release/v1`.\n\n1. Enable \u201cTrusted Publishing\u201d for the project on PyPI and link it to this repository. \n2. Create a GitHub Release (or press **Run workflow** in the *Actions* tab). \n The build artifacts are uploaded and automatically published to PyPI \u2013 **no secret required**.\n\n### 2. Classic API-token publishing\n\nThe fallback workflow in `.github/workflows/publish.yml` is triggered whenever you push a git tag\nthat matches `v*.*.*`.\n\n1. Create a scoped PyPI **API token** with *publish* privileges. \n2. Add it to the repository secrets as `PYPI_API_TOKEN`. \n3. Tag and push a new version:\n\n```cmd\ngit tag v0.2.0\ngit push --tags\n```\n\n## License\n\nThis project is licensed under the **MIT License**. See `LICENSE` for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight OpenTelemetry file exporter that writes traces, logs and metrics to local JSON Lines files",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/Brishen/otel_file_exporter/releases",
"Homepage": "https://github.com/Brishen/otel_file_exporter",
"Issues": "https://github.com/Brishen/otel_file_exporter/issues",
"Source": "https://github.com/Brishen/otel_file_exporter"
},
"split_keywords": [
"opentelemetry",
" tracing",
" logging",
" metrics",
" jsonl",
" observability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c6d869faaa5dc4ad8d3ea7c0a097700f7f7b5234aa2dfca8f0c22209c7b34b7",
"md5": "add77a9fdd315feeefaeb5f9d2471613",
"sha256": "1a91abee915cfc9e28df7d9ec8af44e26dec768af9607ee76b5c19eb03d16479"
},
"downloads": -1,
"filename": "otel_file_exporter-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "add77a9fdd315feeefaeb5f9d2471613",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 10440,
"upload_time": "2025-08-07T07:53:41",
"upload_time_iso_8601": "2025-08-07T07:53:41.293677Z",
"url": "https://files.pythonhosted.org/packages/0c/6d/869faaa5dc4ad8d3ea7c0a097700f7f7b5234aa2dfca8f0c22209c7b34b7/otel_file_exporter-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ea602be79dab0929ed620160530df0e81d2904f47c2890f1ff8855ae3bdbc1ec",
"md5": "93c95f44ea7542888e38a7cf1d58e88c",
"sha256": "69102bebd89a7949baa3a15fdbe35099d76da0c41bc20687bd5d3b925aa64fe4"
},
"downloads": -1,
"filename": "otel_file_exporter-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "93c95f44ea7542888e38a7cf1d58e88c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 12275,
"upload_time": "2025-08-07T07:53:42",
"upload_time_iso_8601": "2025-08-07T07:53:42.447412Z",
"url": "https://files.pythonhosted.org/packages/ea/60/2be79dab0929ed620160530df0e81d2904f47c2890f1ff8855ae3bdbc1ec/otel_file_exporter-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 07:53:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Brishen",
"github_project": "otel_file_exporter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "otel-file-exporter"
}
JSON
