GitHub

otlp_proxy

API reference for otlp_proxy.

Proxying OTLP/HTTP exports from browsers through the app's own HTTP server to a collector (Effect's OtlpProxy).

layer mounts POST /v1/traces, /v1/logs and /v1/metrics on the HttpRouter, adds the configured headers on the server and forwards the body unchanged:

  • The upstream URL comes only from configuration; the request's path and query never reach it.
  • Only application/json and application/x-protobuf bodies are accepted (415 otherwise); only content-type and content-encoding are forwarded, then the configured headers, so a client cannot override them. Upstream requests ask for accept-encoding: identity.
  • Bodies are buffered up to max_body_size (413 beyond it).
  • The upstream status and body come back with only content-type and retry-after; a transport failure is 502 and a timeout 504. Nothing is retried or batched.

Anyone who can reach the routes sends telemetry with the configured credentials: compose authentication, CORS and rate limiting around it.

Types

TypeDefinitionDescription
Signaltype Signal = Literal['traces', 'logs', 'metrics']
Handlertype Handler = Effect[HttpServerResponse, Never, HttpServerRequest]

A route handler forwarding one signal.

Functions

make

make(*, base_url, urls=None, headers=None, max_body_size=None, timeout=None) -> Effect[dict[Signal, Handler], Never, HttpClient]

One handler per signal, forwarding to urls[signal] or else /v1/<signal> below base_url. max_body_size defaults to MaxBodySize, then 10 MiB; timeout to 10 seconds.

ParameterTypeDescription
base_urlstr
urlsMapping[Signal, str] | None = None
headers_headers.Input | None = None
max_body_sizebyte_size.Input | None = None
timeoutDurationInput | None = None

Returns Effect[dict[Signal, Handler], Never, HttpClient]

def make(
    *,
    base_url: str,
    urls: Mapping[Signal, str] | None = None,
    headers: _headers.Input | None = None,
    max_body_size: byte_size.Input | None = None,
    timeout: DurationInput | None = None,
) -> Effect[dict[Signal, Handler], Never, HttpClient]:
    """One handler per signal, forwarding to ``urls[signal]`` or else
    ``/v1/<signal>`` below ``base_url``. ``max_body_size`` defaults to
    ``MaxBodySize``, then 10 MiB; ``timeout`` to 10 seconds."""
    base = _request.post(base_url)

    @gen
    def build():
        client = yield from HttpClient()
        handlers: dict[Signal, Handler] = {}
        for signal in _ALL_SIGNALS:
            explicit = None if urls is None else urls.get(signal)
            url = explicit if explicit is not None else base.append_url(f"/v1/{signal}").url
            handlers[signal] = _make_handler(client, url, headers, max_body_size, timeout)
        return handlers

    return build

layer

layer(*, base_url, urls=None, headers=None, max_body_size=None, timeout=None, prefix=None, signals=None) -> Layer[Never, Never, HttpRouter | HttpClient]

Mounts POST <prefix>/v1/<signal> for each of signals (all three by default).

ParameterTypeDescription
base_urlstr
urlsMapping[Signal, str] | None = None
headers_headers.Input | None = None
max_body_sizebyte_size.Input | None = None
timeoutDurationInput | None = None
prefixstr | None = None
signalsSequence[Signal] | None = None

Returns Layer[Never, Never, HttpRouter | HttpClient]

def layer(
    *,
    base_url: str,
    urls: Mapping[Signal, str] | None = None,
    headers: _headers.Input | None = None,
    max_body_size: byte_size.Input | None = None,
    timeout: DurationInput | None = None,
    prefix: str | None = None,
    signals: Sequence[Signal] | None = None,
) -> Layer[Never, Never, HttpRouter | HttpClient]:
    """Mounts ``POST <prefix>/v1/<signal>`` for each of ``signals`` (all
    three by default)."""

    @gen
    def mount():
        handlers = yield from make(
            base_url=base_url,
            urls=urls,
            headers=headers,
            max_body_size=max_body_size,
            timeout=timeout,
        )
        chosen = _ALL_SIGNALS if signals is None else signals
        yield from _add_routes(prefix, [(signal, handlers[signal]) for signal in chosen])

    return _layer.effect_discard(mount)

layer_from_config

layer_from_config(*, headers=None, max_body_size=None, timeout=None, prefix=None, signals=None) -> Layer[Never, Never, HttpRouter | HttpClient]

layer with each signal's upstream from OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT (else /v1/<signal> below OTEL_EXPORTER_OTLP_ENDPOINT) and headers from OTEL_EXPORTER_OTLP_(<SIGNAL>_)HEADERS unless headers is given. A signal without an endpoint gets no route; invalid configuration is a defect.

ParameterTypeDescription
headers_headers.Input | None = None
max_body_sizebyte_size.Input | None = None
timeoutDurationInput | None = None
prefixstr | None = None
signalsSequence[Signal] | None = None

Returns Layer[Never, Never, HttpRouter | HttpClient]

def layer_from_config(
    *,
    headers: _headers.Input | None = None,
    max_body_size: byte_size.Input | None = None,
    timeout: DurationInput | None = None,
    prefix: str | None = None,
    signals: Sequence[Signal] | None = None,
) -> Layer[Never, Never, HttpRouter | HttpClient]:
    """``layer`` with each signal's upstream from
    ``OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT`` (else ``/v1/<signal>`` below
    ``OTEL_EXPORTER_OTLP_ENDPOINT``) and headers from
    ``OTEL_EXPORTER_OTLP_(<SIGNAL>_)HEADERS`` unless ``headers`` is given.
    A signal without an endpoint gets no route; invalid configuration is a
    defect."""

    @gen
    def mount():
        client = yield from HttpClient()
        routes: list[tuple[Signal, Handler]] = []
        for signal in _ALL_SIGNALS if signals is None else signals:
            env_signal = _ENV_SIGNALS[signal]
            url = yield from env.endpoint(env_signal)
            if url is None:
                continue
            signal_headers = (
                headers if headers is not None else (yield from env.headers(env_signal))
            )
            routes.append(
                (signal, _make_handler(client, str(url), signal_headers, max_body_size, timeout))
            )
        yield from _add_routes(prefix, routes)

    return _layer.effect_discard(mount.or_die())