Skip to main content

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-proxy command with reload, port override, and config selection
  • Drop‑in APM intake compatibility — forwards to Elastic APM or runs in capture‑only mode
  • Real User Monitoring (RUM) intake compatibility — supports /intake/v2/rum/events
  • 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-proxy CLI 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

# Optional corporate proxy settings (also supported in lowercase)
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

B. Custom .env file

apm-proxy --env /path/to/custom.env

[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

Outbound forwarding honors the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. These variables can be set in the shell or in the .env file before starting the proxy.

Start with TOML:

apm-proxy --config config.toml

Configuration Precedence

  1. TOML overrides .env
  2. 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:

  • Transaction
  • Span
  • Error
  • Metricset
  • Metadata
  • NdjsonEvent (generic wrapper)

Browser RUM agents can send NDJSON to /intake/v2/rum/events; those payloads are captured and forwarded like regular APM events.

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 .env or 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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apm-proxy 0.1.3
File Size Uploaded Provenance Actions
apm_proxy-0.1.3.tar.gz 10.4 kB With provenance Details for apm_proxy-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apm-proxy 0.1.3
File Interpreter ABI Platform Actions
apm_proxy-0.1.3-py3-none-any.whl Python 3 none any Details for apm_proxy-0.1.3-py3-none-any.whl

Total release size: 20.6 kB

Release files / apm_proxy-0.1.3.tar.gz

Download URL apm_proxy-0.1.3.tar.gz
Size 10.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f179241ef4758a5471299b2f0dd4e633f82281014704172501d5070804eb6760
BLAKE2b-256 checksum
How to use checksums
c0af822188309a8c5793a54f27b0bc97b3c358b31e9aa199d21efd052b4bb16e
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 Sep 1, 2026.

Transparency log

Release files / apm_proxy-0.1.3-py3-none-any.whl

Download URL apm_proxy-0.1.3-py3-none-any.whl
Size 10.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b57e9ecac501941a3e2fa6ca55b5acd432ccfe0fa6f33b02bf2318dceb6d38af
BLAKE2b-256 checksum
How to use checksums
01924df7e69eacbb960adf8156be6bf35d87e98c008cf8696b3cc65ee14e7e37
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 Sep 1, 2026.

Transparency log

Security for apm-proxy 0.1.3

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.

Select from 2 files

Attestation for apm_proxy-0.1.3.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 Sep 1, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page