APM Proxy — Typed Elastic APM NDJSON Proxy
A fully typed, FastAPI‑based Elastic APM proxy designed for debugging, observability pipelines, traffic inspection, and local/offline APM analysis.
It acts as a drop‑in replacement for the Elastic APM intake API, with powerful enhancements:
⭐ Core Features
- Full NDJSON capture — persist raw APM events to disk for replay, audit, or offline analysis
- Header‑aware grouping — group events by transaction, span, trace, or custom headers
- Full header forwarding — preserves
traceparent,X-APM-*, and all custom headers - Typed Pydantic models — parse NDJSON into structured Python objects
- Configurable logging — console logging, file logging, and debug dumps
- Flexible configuration —
.env, custom.env, or structured TOML - CLI runner —
apm-proxycommand with reload, port override, and config selection - Drop‑in APM intake compatibility — forwards to Elastic APM or runs in capture‑only mode
- Zero‑config development mode — instant startup with sensible defaults
- Safe offline mode — inspect APM traffic without forwarding anything
- Full request header printing — see exactly what your APM agents send
- Span + transaction correlation — reconstruct traces from NDJSON
- Supports browser, Node, Python, Go, Java APM agents
This proxy is ideal for debugging distributed traces, reverse‑engineering APM agents, building custom telemetry pipelines, and capturing APM traffic in development.
1. Installation
Clone the repository:
git clone https://github.com/your-org/apm-proxy.git
cd apm-proxy
Install in editable mode:
pip install -e .
This installs:
- The proxy package
- The
apm-proxyCLI command - All required dependencies
2. Configuration
The proxy supports three configuration sources:
A. Default .env file
Place a .env file in the project root:
APM_SERVER=https://apm.example.com
APM_TOKEN=secret-token
APM_FORWARD=true
APM_SAVE=true
APM_SAVE_DIR=./apm_logs
APM_LOG_PREFIX=events
APM_PRINT=false
APM_LOG_LEVEL=INFO
APM_LOG_TO_FILE=true
APM_LOG_FILE=apm_proxy.log
APM_PORT=8200
B. Custom .env file
apm-proxy --env /path/to/custom.env
C. TOML configuration (recommended)
[apm_server]
url = "https://apm.example.com"
token = "secret-token"
forward = true
[logs]
save = true
save_dir = "./apm_logs"
prefix = "events"
[console]
print_payloads = false
[logging]
level = "INFO"
to_file = true
file = "apm_proxy.log"
[grouping]
headers = ["X-APM-Transaction-ID", "X-APM-Span-ID"]
[proxy_server]
port = 8200
Start with TOML:
apm-proxy --config config.toml
Configuration Precedence
- TOML overrides
.env - CLI overrides both
Example:
apm-proxy --env base.env --config prod.toml --port 9999
3. Startup Modes
Default startup
apm-proxy
Uses .env in project root.
Start with custom .env
apm-proxy --env staging.env
Start with TOML
apm-proxy --config config.toml
Override port
apm-proxy --port 9000
Enable auto‑reload (development)
apm-proxy --reload
Print raw NDJSON payloads
APM_PRINT=true
Or inline:
APM_PRINT=true apm-proxy
Enable debug logging
APM_LOG_LEVEL=DEBUG
Disable forwarding (local capture only)
APM_FORWARD=false
4. Typed NDJSON Models
The proxy parses NDJSON events into typed Pydantic models:
TransactionSpanErrorMetricsetMetadataNdjsonEvent(generic wrapper)
This enables:
- Deterministic inspection
- Enrichment
- Filtering
- Routing
- Debugging
- Custom processing pipelines
Example:
if event.is_transaction():
tx = Transaction(transaction=event.raw["transaction"])
5. Logging & Debugging
The proxy uses Rich for colored logs:
- Colored event types
- Pretty tracebacks
- Optional file logging
- Log levels from
.envor TOML - Full header dumps
- Grouping header dumps
- NDJSON payload dumps
Log settings
[logging]
level = "DEBUG"
to_file = true
file = "proxy.log"
Console payload printing
[console]
print_payloads = true
6. NDJSON Capture
Captured NDJSON is written with contextual headers:
# ---- Received: 2026-08-18T09:15:12.123Z ----
# ---- X-APM-Transaction-ID: abc123 ----
# ---- X-APM-Span-ID: def456 ----
{"metadata": ...}
{"transaction": ...}
{"span": ...}
This makes it ideal for:
- replay
- offline analysis
- debugging
- trace reconstruction
- custom pipelines
7. Dependencies
dependencies = [
"fastapi",
"uvicorn[standard]",
"python-dotenv",
"requests",
"pydantic>=2.0",
"rich",
"httpx",
"tomli; python_version<'3.11'"
]
Dependency Breakdown
| Package | Purpose |
|---|---|
| fastapi | HTTP server |
| uvicorn[standard] | ASGI runtime |
| python-dotenv | .env loading |
| requests | Forwarding NDJSON |
| pydantic>=2.0 | Typed NDJSON models |
| rich | Colored logs |
| httpx | Async forwarding |
| tomllib / tomli | TOML config support |
8. CLI Summary
| Flag | Description |
|---|---|
--env PATH |
Use custom .env file |
--config PATH |
Use TOML config file |
--port N |
Override port |
--reload |
Enable auto‑reload |
Metadata
Release files for apm-proxy 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| apm_proxy-0.1.2.tar.gz | 9.5 kB | With provenance | Details for apm_proxy-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| apm_proxy-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for apm_proxy-0.1.2-py3-none-any.whl |
Total release size: 19.1 kB
Release files / apm_proxy-0.1.2.tar.gz
| Download URL | apm_proxy-0.1.2.tar.gz |
|---|---|
| Size | 9.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
abbd51115ecf3dfb752424a2e9b6dadfe208f412f74dfa9f7f55cc920db89086
|
|
BLAKE2b-256 checksum How to use checksums |
e9fbf77605f55de8f9fb0990bb3c71e0d52509cf76452918cacb00aedba0a269
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logRelease files / apm_proxy-0.1.2-py3-none-any.whl
| Download URL | apm_proxy-0.1.2-py3-none-any.whl |
|---|---|
| Size | 9.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7bfe78d0edf0674eb10efbed8e1af389cb21b1dcbcb6c6be9523cf3dfc77c050
|
|
BLAKE2b-256 checksum How to use checksums |
f6ee1762c802352170bff9043f9117b815fd49b2d293b4e790e1b36b48cb4caf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logSecurity for apm-proxy 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for apm_proxy-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.