dash0hq · mmanciop · Aug 6, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
@@ -0,0 +1,41 @@
+name: Synchronize docs to the Dash0 website
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: Only verify transformations + coverage; do not open a PR.
+        type: boolean
+        default: true
+  workflow_call:
+    inputs:
+      dry-run:
+        type: boolean
+        default: false
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/sync-docs/**'
+      - '.github/workflows/sync-docs.yml'
+
+jobs:
+  sync-docs:
+    name: Sync docs to Dash0 website
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync docs to the Dash0 website
+        uses: dash0hq/sync-docs-action@3fbe55fed800da21ee24d6b6dba1a86435f61565  # v0.4.0
+        with:
+          dry-run: ${{ github.event_name == 'pull_request' || inputs.dry-run }}
+          target-repository: ${{ secrets.SYNC_DOCUMENTATION_TARGET_REPOSITORY }}
+          target-directory: ${{ secrets.SYNC_DOCUMENTATION_TARGET_DIRECTORY }}
+          target-github-token: ${{ secrets.DASH0_WEBSITE_SYNC_TOKEN }}
+          pr-branch: sync/opentelemetry-python-distribution-docs
+          pr-title: "docs: synchronize Python distribution documentation"
+          pr-body: |
+            Synchronizes the OpenTelemetry Python distribution documentation
+            from [dash0hq/opentelemetry-python-distribution](https://github.com/dash0hq/opentelemetry-python-distribution).
+          pr-reviewers: mmanciop
@@ -0,0 +1,62 @@
+common:
+  - description: Strip the leading H1 heading (the frontmatter title replaces it on the website).
+    type: replace-regex
+    find: '^# [^\n]*\n'
+    replace: ""
+
+  - description: Rewrite relative cross-references between distribution docs to absolute website paths.
+    type: replace-regex
+    find: '\]\(([a-z][a-z0-9-]*)\)'
+    replace: '](/docs/dash0/opentelemetry/distributions/python/\1)'
+    required: false
+
+files:
+  - source: docs/overview.md
+    target: dash0/opentelemetry/distributions/python/overview.md
+    title: Dash0 OpenTelemetry Python Distribution
+    description: Overview of the Dash0 OpenTelemetry distribution for Python — zero-code instrumentation with pure-Python OTLP export and no native dependencies.
+
+  - source: docs/getting-started.md
+    target: dash0/opentelemetry/distributions/python/getting-started.md
+    title: Getting Started
+    description: Install the Dash0 OpenTelemetry Python distribution and send your first traces, metrics, and logs in minutes.
+
+  - source: docs/configuration.md
+    target: dash0/opentelemetry/distributions/python/configuration.md
+    title: Configuration
+    description: All Dash0-specific and standard OpenTelemetry environment variables for the Python distribution.
+
+  - source: docs/auto-instrumentation.md
+    target: dash0/opentelemetry/distributions/python/auto-instrumentation.md
+    title: Auto-instrumentation
+    description: The full set of libraries and frameworks automatically instrumented by the Dash0 OpenTelemetry Python distribution.
+
+  - source: docs/resource-detection.md
+    target: dash0/opentelemetry/distributions/python/resource-detection.md
+    title: Resource Detection
+    description: Built-in resource detectors for distribution metadata, Kubernetes pod UID, and service name fallback.
+
+  - source: docs/kubernetes-injection.md
+    target: dash0/opentelemetry/distributions/python/kubernetes-injection.md
+    title: Kubernetes Injection
+    description: How the Dash0 Python distribution is injected into Kubernetes workloads via sitecustomize.py and PYTHONPATH, with safety guards and graceful self-deactivation.
+
+  - source: docs/exporters.md
+    target: dash0/opentelemetry/distributions/python/exporters.md
+    title: OTLP Exporters
+    description: Pure-Python OTLP/HTTP and OTLP/gRPC exporters with no native dependencies, intelligent endpoint rewriting, and drop-in compatibility with the upstream exporter names.
+
+coverage:
+  include:
+    - "docs/*.md"
+    - "docs/**/*.md"
+  ignore:
+    - "docs/brainstorms/2026-07-22-distro-publishing-requirements.md"
+    - "docs/plans/2026-07-22-001-feat-self-hosted-index-publishing-plan.md"
+
+nav:
+  target: dash0/opentelemetry/distributions/python/nav.json
+  order: 66
+  id: opentelemetry-python-distribution
+  parentPath: Dash0 Distributions
+  title: Python
@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+Coding conventions and agentic guidelines for the Dash0 OpenTelemetry Python distribution.
+
+## Project overview
+
+A `uv` workspace. The Dash0-authored code lives entirely in
+`packages/dash0-opentelemetry/`. The vendored pyproto exporter packages
+(`packages/opentelemetry-*/`) are kept close to upstream; do not apply local
+style changes to them (they are excluded from linting).
+
+## Coding conventions
+
+- Every function has a name that precisely describes what it does.
+- Prefer `from x import y` over `import x`.
+- Keep the distribution vendor-neutral except where Dash0 behavior is intentional.
+
+## Maintaining the website documentation
+
+The `docs/` directory contains Markdown files that are synced to the Dash0
+website via `.github/workflows/sync-docs.yml`. Keep them accurate whenever
+the relevant source changes.
+
+### Source-of-truth mapping
+
+Each doc file has a single authoritative source. When those sources change,
+update the corresponding doc.
+
+| Doc file | Authoritative source(s) | What to check |
+|---|---|---|
+| `docs/overview.md` | `README.rst`, `packages/dash0-opentelemetry/README.rst` | Overall description, key capabilities, architecture |
+| `docs/getting-started.md` | `README.rst` (Quick start section), `examples/dash0-distro-flask/` | Quick start commands, example setup |
+| `docs/configuration.md` | `packages/dash0-opentelemetry/src/dash0/opentelemetry/_environment_variables.py`, `packages/dash0-opentelemetry/src/dash0/opentelemetry/distro.py`, `packages/dash0-opentelemetry/src/dash0/opentelemetry/settings.py` | All `DASH0_*` variables and the `OTEL_*` defaults the distro sets |
+| `docs/auto-instrumentation.md` | `packages/dash0-opentelemetry/pyproject.toml` (the `[project].dependencies` block, approx. lines 50–115) | The exact list of `opentelemetry-instrumentation-*` packages |
+| `docs/resource-detection.md` | `packages/dash0-opentelemetry/src/dash0/opentelemetry/resource.py`, `packages/dash0-opentelemetry/README.rst` | Detector names, attributes emitted, detection logic |
+| `docs/kubernetes-injection.md` | `packages/dash0-opentelemetry/src/dash0/opentelemetry/injector/sitecustomize.py` | Safety checks, deactivation logic, PYTHONPATH bridge |
+| `docs/exporters.md` | `packages/dash0-opentelemetry/src/dash0/opentelemetry/distro.py`, `packages/opentelemetry-exporter-otlp-proto-http/`, `packages/opentelemetry-exporter-otlp-proto-grpc/` | Exporter names, protocol selection, port-rewriting logic |
+
+### When to update docs
+
+Update the relevant doc file whenever a PR:
+
+- Adds, renames, or removes a `DASH0_*` environment variable → `docs/configuration.md`
+- Adds or removes an `opentelemetry-instrumentation-*` dependency → `docs/auto-instrumentation.md`
+- Changes how a resource detector works or what attributes it emits → `docs/resource-detection.md`
+- Changes the `sitecustomize.py` safety checks or deactivation flow → `docs/kubernetes-injection.md`
+- Changes the exporter selection logic, port-rewriting, or protocol handling → `docs/exporters.md`
+- Changes the overall architecture, entry points, or quick-start workflow → `docs/overview.md`, `docs/getting-started.md`
+
+### Auto-instrumentation list: always derive from source
+
+**Never maintain `docs/auto-instrumentation.md` by hand.** Always derive the
+library table from the actual dependency block in
+`packages/dash0-opentelemetry/pyproject.toml`.
+
+To regenerate the list:
+
+```bash
+grep 'opentelemetry-instrumentation-' packages/dash0-opentelemetry/pyproject.toml \
+  | sed 's/.*"\(opentelemetry-instrumentation-[a-z0-9_-]*\).*/\1/'
+```
+
+Map each package name to its target library using the
+[opentelemetry-python-contrib instrumentation index](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation)
+and update the tables in `docs/auto-instrumentation.md` to match.
+Keep the same category groupings (Web frameworks, HTTP clients, Databases, etc.).
+Add new packages to the appropriate category; remove packages that are no longer in `pyproject.toml`.
+
+Also update the "What is not included" section whenever a package is deliberately
+excluded (the comments in `pyproject.toml` explain the reason for each exclusion).
+
+### Keeping transformations.yaml in sync
+
+`.github/workflows/sync-docs/transformations.yaml` declares which `docs/*.md`
+files are synced to the website. It has a `coverage` block that fails CI if a
+file under `docs/*.md` is not explicitly listed.
+
+When you add a new `docs/*.md` file, add a corresponding entry to the `files:`
+block in `transformations.yaml` with:
+- `source:` — path relative to the repo root (e.g., `docs/new-topic.md`)
+- `target:` — destination path on the website (follow the `opentelemetry/python/<slug>.md` pattern)
+- `title:` — short display title for the page
+- `description:` — one-sentence description used as the page meta description
+
+When you remove a `docs/*.md` file, remove the corresponding `files:` entry too.
+
+### Doc style rules
+
+- One sentence per line (semantic line breaks) — this is the project's RST convention carried into Markdown.
+- Sentence-case headings: `## Getting started`, not `## Getting Started`.
+- Active voice: "The distro sets" not "The value is set by".
+- Inline code for all env var names, file paths, package names, and CLI commands.
+- No em-dashes; use shorter sentences instead.
+- Tables for environment variables: three columns (variable name, description, notes/default).
+- Do not add comments explaining what the doc is or when it was updated.
@@ -0,0 +1,163 @@
+# Auto-instrumentation
+
+## How it works
+
+The distribution depends on the full set of upstream auto-instrumentation packages, all pinned to a single contrib version.
+When `opentelemetry-instrument` starts your application, each installed instrumentor is activated automatically.
+Instrumentors whose target library is not installed are silently skipped.
+**No `opentelemetry-bootstrap` step is required.**
+
+## Defensive loading
+
+Each instrumentor is loaded defensively: if one fails (due to a version incompatibility, a missing dependency, or a bug), the failure is logged and the instrumentor is skipped.
+Instrumentation of the rest of the process continues.
+A single broken instrumentor does not abort the entire auto-instrumentation process.
+
+## Supported libraries and frameworks
+
+### Web frameworks
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| Flask | [`opentelemetry-instrumentation-flask`](https://pypi.org/project/opentelemetry-instrumentation-flask/) |
+| Django | [`opentelemetry-instrumentation-django`](https://pypi.org/project/opentelemetry-instrumentation-django/) |
+| FastAPI | [`opentelemetry-instrumentation-fastapi`](https://pypi.org/project/opentelemetry-instrumentation-fastapi/) |
+| Falcon | [`opentelemetry-instrumentation-falcon`](https://pypi.org/project/opentelemetry-instrumentation-falcon/) |
+| Pyramid | [`opentelemetry-instrumentation-pyramid`](https://pypi.org/project/opentelemetry-instrumentation-pyramid/) |
+| Starlette | [`opentelemetry-instrumentation-starlette`](https://pypi.org/project/opentelemetry-instrumentation-starlette/) |
+| Tornado | [`opentelemetry-instrumentation-tornado`](https://pypi.org/project/opentelemetry-instrumentation-tornado/) |
+| ASGI | [`opentelemetry-instrumentation-asgi`](https://pypi.org/project/opentelemetry-instrumentation-asgi/) |
+| WSGI | [`opentelemetry-instrumentation-wsgi`](https://pypi.org/project/opentelemetry-instrumentation-wsgi/) |
+
+</div>
+
+### HTTP clients
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| aiohttp client | [`opentelemetry-instrumentation-aiohttp-client`](https://pypi.org/project/opentelemetry-instrumentation-aiohttp-client/) |
+| aiohttp server | [`opentelemetry-instrumentation-aiohttp-server`](https://pypi.org/project/opentelemetry-instrumentation-aiohttp-server/) |
+| httpx | [`opentelemetry-instrumentation-httpx`](https://pypi.org/project/opentelemetry-instrumentation-httpx/) |
+| requests | [`opentelemetry-instrumentation-requests`](https://pypi.org/project/opentelemetry-instrumentation-requests/) |
+| urllib | [`opentelemetry-instrumentation-urllib`](https://pypi.org/project/opentelemetry-instrumentation-urllib/) |
+| urllib3 | [`opentelemetry-instrumentation-urllib3`](https://pypi.org/project/opentelemetry-instrumentation-urllib3/) |
+
+</div>
+
+### Databases and caches
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| psycopg2 (PostgreSQL) | [`opentelemetry-instrumentation-psycopg2`](https://pypi.org/project/opentelemetry-instrumentation-psycopg2/) |
+| psycopg (PostgreSQL) | [`opentelemetry-instrumentation-psycopg`](https://pypi.org/project/opentelemetry-instrumentation-psycopg/) |
+| asyncpg (async PostgreSQL) | [`opentelemetry-instrumentation-asyncpg`](https://pypi.org/project/opentelemetry-instrumentation-asyncpg/) |
+| aiopg (async PostgreSQL) | [`opentelemetry-instrumentation-aiopg`](https://pypi.org/project/opentelemetry-instrumentation-aiopg/) |
+| mysql-connector-python | [`opentelemetry-instrumentation-mysql`](https://pypi.org/project/opentelemetry-instrumentation-mysql/) |
+| mysqlclient | [`opentelemetry-instrumentation-mysqlclient`](https://pypi.org/project/opentelemetry-instrumentation-mysqlclient/) |
+| PyMySQL | [`opentelemetry-instrumentation-pymysql`](https://pypi.org/project/opentelemetry-instrumentation-pymysql/) |
+| pymssql (SQL Server) | [`opentelemetry-instrumentation-pymssql`](https://pypi.org/project/opentelemetry-instrumentation-pymssql/) |
+| SQLite3 | [`opentelemetry-instrumentation-sqlite3`](https://pypi.org/project/opentelemetry-instrumentation-sqlite3/) |
+| PyMongo (MongoDB) | [`opentelemetry-instrumentation-pymongo`](https://pypi.org/project/opentelemetry-instrumentation-pymongo/) |
+| Cassandra / ScyllaDB | [`opentelemetry-instrumentation-cassandra`](https://pypi.org/project/opentelemetry-instrumentation-cassandra/) |
+| Redis | [`opentelemetry-instrumentation-redis`](https://pypi.org/project/opentelemetry-instrumentation-redis/) |
+| pymemcache | [`opentelemetry-instrumentation-pymemcache`](https://pypi.org/project/opentelemetry-instrumentation-pymemcache/) |
+| DB-API 2.0 | [`opentelemetry-instrumentation-dbapi`](https://pypi.org/project/opentelemetry-instrumentation-dbapi/) |
+
+</div>
+
+### ORMs and query builders
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| SQLAlchemy | [`opentelemetry-instrumentation-sqlalchemy`](https://pypi.org/project/opentelemetry-instrumentation-sqlalchemy/) |
+| TortoiseORM | [`opentelemetry-instrumentation-tortoiseorm`](https://pypi.org/project/opentelemetry-instrumentation-tortoiseorm/) |
+
+</div>
+
+### Message queues and task queues
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| confluent-kafka | [`opentelemetry-instrumentation-confluent-kafka`](https://pypi.org/project/opentelemetry-instrumentation-confluent-kafka/) |
+| kafka-python | [`opentelemetry-instrumentation-kafka-python`](https://pypi.org/project/opentelemetry-instrumentation-kafka-python/) |
+| aiokafka | [`opentelemetry-instrumentation-aiokafka`](https://pypi.org/project/opentelemetry-instrumentation-aiokafka/) |
+| aio-pika (RabbitMQ) | [`opentelemetry-instrumentation-aio-pika`](https://pypi.org/project/opentelemetry-instrumentation-aio-pika/) |
+| pika (RabbitMQ) | [`opentelemetry-instrumentation-pika`](https://pypi.org/project/opentelemetry-instrumentation-pika/) |
+| Celery | [`opentelemetry-instrumentation-celery`](https://pypi.org/project/opentelemetry-instrumentation-celery/) |
+| Remoulade | [`opentelemetry-instrumentation-remoulade`](https://pypi.org/project/opentelemetry-instrumentation-remoulade/) |
+| AWS SQS (boto3sqs) | [`opentelemetry-instrumentation-boto3sqs`](https://pypi.org/project/opentelemetry-instrumentation-boto3sqs/) |
+
+</div>
+
+### Async and concurrency
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| asyncio | [`opentelemetry-instrumentation-asyncio`](https://pypi.org/project/opentelemetry-instrumentation-asyncio/) |
+| threading | [`opentelemetry-instrumentation-threading`](https://pypi.org/project/opentelemetry-instrumentation-threading/) |
+
+</div>
+
+### CLI frameworks
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| Click | [`opentelemetry-instrumentation-click`](https://pypi.org/project/opentelemetry-instrumentation-click/) |
+| asyncclick | [`opentelemetry-instrumentation-asyncclick`](https://pypi.org/project/opentelemetry-instrumentation-asyncclick/) |
+
+</div>
+
+### AI and cloud
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| OpenAI | [`opentelemetry-instrumentation-openai-v2`](https://pypi.org/project/opentelemetry-instrumentation-openai-v2/) |
+| Google Vertex AI | [`opentelemetry-instrumentation-vertexai`](https://pypi.org/project/opentelemetry-instrumentation-vertexai/) |
+| boto3 / botocore (AWS SDK) | [`opentelemetry-instrumentation-botocore`](https://pypi.org/project/opentelemetry-instrumentation-botocore/) |
+
+</div>
+
+### Other
+
+<div class="two-col-lib-table">
+
+| Library | Instrumentation package |
+|---|---|
+| gRPC | [`opentelemetry-instrumentation-grpc`](https://pypi.org/project/opentelemetry-instrumentation-grpc/) |
+| Jinja2 | [`opentelemetry-instrumentation-jinja2`](https://pypi.org/project/opentelemetry-instrumentation-jinja2/) |
+| logging | [`opentelemetry-instrumentation-logging`](https://pypi.org/project/opentelemetry-instrumentation-logging/) |
+| structlog | [`opentelemetry-instrumentation-structlog`](https://pypi.org/project/opentelemetry-instrumentation-structlog/) |
+| System metrics | [`opentelemetry-instrumentation-system-metrics`](https://pypi.org/project/opentelemetry-instrumentation-system-metrics/) |
+| Exception handling | [`opentelemetry-instrumentation-exceptions`](https://pypi.org/project/opentelemetry-instrumentation-exceptions/) |
+
+</div>
+
+## Propagators
+
+The AWS X-Ray propagator ([`opentelemetry-propagator-aws-xray`](https://pypi.org/project/opentelemetry-propagator-aws-xray/)) is explicitly included.
+The W3C TraceContext and Baggage propagators are built into the OpenTelemetry SDK and always available.
+B3 format propagation is not included; it requires the separate [`opentelemetry-propagator-b3`](https://pypi.org/project/opentelemetry-propagator-b3/) package, which is not a dependency of this distribution.
+
+## What is not included
+
+The following packages are deliberately excluded:
+
+- [`opentelemetry-exporter-prometheus`](https://pypi.org/project/opentelemetry-exporter-prometheus/): not needed; OTLP metrics export covers this use case.
+- [`opentelemetry-propagator-ot-trace`](https://pypi.org/project/opentelemetry-propagator-ot-trace/): legacy propagator not required for Dash0.
+- [`opentelemetry-instrumentation-aws-lambda`](https://pypi.org/project/opentelemetry-instrumentation-aws-lambda/): Lambda deployments use a dedicated instrumentation layer.