Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Packages: `runtime-node`, `otlp-ingester`, Python adapter (`adapters/python`).
- Kept: `service.instance.id` (the ingester needs it), `host.name` (container and pod names; on a laptop or VM it is the machine's name), `process.pid`, `process.runtime.*`, `os.type`, `host.arch`, and the coarse `user_agent.browser` / `.os` / `.device` / `.bot` fields.
- Keep them with `keepIdentifyingAttributes: true` or a list of keys (`initAutterServer`, `registerAutter`), `keep_identifying_attributes=` in Python `init_tracing()`, or `AUTTER_KEEP_IDENTIFYING_ATTRIBUTES` (`true`, or a comma-separated list) for the SDKs and the ingester. Drop more keys, such as `host.name`, with `dropAttributes` / `drop_attributes=` / `AUTTER_DROP_ATTRIBUTES`. An attribute the SDK keeps is stored only if the ingester keeps it too: set `AUTTER_KEEP_IDENTIFYING_ATTRIBUTES` on both.
- Spans already stored keep these attributes until their TTL expires.
- Opt-in hashed client IP (`runtime-node`, Python adapter, `otlp-ingester`), to count distinct clients without storing addresses: `hashClientIp: true | { salt }`, `init_tracing(hash_client_ip=True, client_ip_salt=...)`, or `AUTTER_HASH_CLIENT_IP=true` with `AUTTER_CLIENT_IP_SALT` (SDKs and ingester). The client's address (`client.address`, then `http.client_ip`, then on server spans the socket peer, which behind a proxy is the proxy) is normalised and exported as `client.address_hash`: HMAC-SHA256 under the secret salt, 32 hex characters, identical in the Node SDK, the Python adapter and the ingester for the same salt (shared vectors in `test-vectors/redaction.json`, `clientIpHash`). The raw address is still dropped. Off by default; on without a salt of at least 16 characters it hashes nothing and warns once, never an unsalted hash. The ingester keeps a hash it receives and does not hash it again. A hashed IP is still pseudonymous personal data in some readings of privacy law: treat the salt as a secret.

## [1.18.0] - 2026-11-14

Expand Down
73 changes: 69 additions & 4 deletions adapters/python/autter_tracing.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,14 @@

try: # imported as part of a package
from .redact import (
CLIENT_IP_HASH_ATTRIBUTE,
CLIENT_IP_SALT_ENV,
CLIENT_IP_SALT_MIN_LENGTH,
DROP_ATTRIBUTES_ENV,
HASH_CLIENT_IP_ENV,
client_ip_of,
hash_client_ip,
usable_client_ip_salt,
KEEP_IDENTIFYING_ATTRIBUTES_ENV,
drop_attributes_from_env,
drop_identifying_attributes,
Expand All @@ -100,7 +107,14 @@
)
except ImportError: # copied next to the app as a plain module
from redact import (
CLIENT_IP_HASH_ATTRIBUTE,
CLIENT_IP_SALT_ENV,
CLIENT_IP_SALT_MIN_LENGTH,
DROP_ATTRIBUTES_ENV,
HASH_CLIENT_IP_ENV,
client_ip_of,
hash_client_ip,
usable_client_ip_salt,
KEEP_IDENTIFYING_ATTRIBUTES_ENV,
drop_attributes_from_env,
drop_identifying_attributes,
Expand Down Expand Up @@ -561,11 +575,42 @@ def _without_identifying_resource(resource: Resource, dropped: frozenset) -> Res
return result


def _redacted(span: ReadableSpan, redact: bool = True, dropped: Optional[frozenset] = None) -> ReadableSpan:
def _client_ip_hasher(enabled: Optional[bool], salt: Optional[str]) -> Optional[Any]:
"""The hasher for ``hash_client_ip`` (default ``AUTTER_HASH_CLIENT_IP``)
with ``salt`` (default ``AUTTER_CLIENT_IP_SALT``), or ``None`` when off.
On without a usable salt it stays off with one warning: never an
unsalted hash. The salt is never logged."""
if enabled is None:
enabled = _env_flag(HASH_CLIENT_IP_ENV)
if not enabled:
return None
usable = usable_client_ip_salt(salt if salt is not None else os.environ.get(CLIENT_IP_SALT_ENV))
if usable is None:
LOGGER.warning(
"[autter-runtime] hash_client_ip is on but no salt of at least %d characters is set "
"(client_ip_salt= or %s): client IP addresses are dropped and not hashed.",
CLIENT_IP_SALT_MIN_LENGTH,
CLIENT_IP_SALT_ENV,
)
return None
return lambda ip: hash_client_ip(usable, ip)


def _redacted(
span: ReadableSpan, redact: bool = True, dropped: Optional[frozenset] = None, hasher: Optional[Any] = None
) -> ReadableSpan:
def clean(attributes: Any) -> Any:
kept = drop_identifying_attributes(attributes, dropped)
return redact_attributes(kept) if redact else kept

attributes = clean(span.attributes)
if hasher is not None and (span.attributes or {}).get(CLIENT_IP_HASH_ATTRIBUTE) is None:
# From the raw address, before it was dropped; a hash already on the
# span (set upstream) is left alone.
ip = client_ip_of(span.attributes, span.kind == SpanKind.SERVER)
if ip:
attributes = {**(attributes or {}), CLIENT_IP_HASH_ATTRIBUTE: hasher(ip)}

events = [Event(event.name, clean(event.attributes), event.timestamp) for event in span.events]
links = [Link(link.context, clean(link.attributes)) for link in span.links]
status = span.status
Expand All @@ -574,7 +619,7 @@ def clean(attributes: Any) -> Any:
return _CopiedSpan(
span,
name=redact_text(span.name) if redact else span.name,
attributes=clean(span.attributes),
attributes=attributes,
events=events,
links=links,
status=status,
Expand All @@ -601,6 +646,12 @@ class RedactingSpanExporter(SpanExporter):
(``True`` or a list of keys; default ``AUTTER_KEEP_IDENTIFYING_ATTRIBUTES``)
keeps them; ``drop_attributes`` (default ``AUTTER_DROP_ATTRIBUTES``, a
comma-separated list) drops more keys, such as ``host.name``.

``hash_client_ip`` (default ``AUTTER_HASH_CLIENT_IP``, off) adds
``client.address_hash``, HMAC-SHA256 of the client's normalised address
under ``client_ip_salt`` (default ``AUTTER_CLIENT_IP_SALT``, at least 16
characters; without one nothing is hashed). Same hash as
@autter/runtime-node and the ingester for the same salt.
"""

def __init__(
Expand All @@ -610,13 +661,16 @@ def __init__(
redact: bool = True,
keep_identifying_attributes: Any = None,
drop_attributes: Optional[Sequence[str]] = None,
hash_client_ip: Optional[bool] = None,
client_ip_salt: Optional[str] = None,
):
self._exporter = exporter
self._redact = redact
self._dropped = _keys_to_drop(keep_identifying_attributes, drop_attributes)
self._hasher = _client_ip_hasher(hash_client_ip, client_ip_salt)

def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
return self._exporter.export([_redacted(span, self._redact, self._dropped) for span in spans])
return self._exporter.export([_redacted(span, self._redact, self._dropped, self._hasher) for span in spans])

def shutdown(self) -> None:
self._exporter.shutdown()
Expand Down Expand Up @@ -663,6 +717,8 @@ def init_tracing(
metric_exporter: Optional[MetricExporter] = None,
keep_identifying_attributes: Any = None,
drop_attributes: Optional[Sequence[str]] = None,
hash_client_ip: Optional[bool] = None,
client_ip_salt: Optional[str] = None,
) -> TracerProvider:
"""A TracerProvider that head-samples as configured and always exports
errors, registered as the global provider.
Expand All @@ -684,6 +740,10 @@ def init_tracing(
them too unless it is given the same setting.
* ``drop_attributes`` (default ``AUTTER_DROP_ATTRIBUTES``): more keys to
drop the same way, such as ``["host.name"]``.
* ``hash_client_ip`` (default ``AUTTER_HASH_CLIENT_IP``, off) and
``client_ip_salt`` (default ``AUTTER_CLIENT_IP_SALT``): add
``client.address_hash``, a keyed hash of the client's address (see
:class:`RedactingSpanExporter`).
* ``count_requests`` (default: on, unless ``AUTTER_COUNT_REQUESTS=false``;
``False`` turns it off): count every HTTP request, sampled or not
(:class:`CountRequests`), in a delta histogram sent through
Expand Down Expand Up @@ -747,7 +807,12 @@ def init_tracing(

exporter = OTLPSpanExporter()
exporter = RedactingSpanExporter(
exporter, redact=redact, keep_identifying_attributes=keep_identifying_attributes, drop_attributes=drop_attributes
exporter,
redact=redact,
keep_identifying_attributes=keep_identifying_attributes,
drop_attributes=drop_attributes,
hash_client_ip=hash_client_ip,
client_ip_salt=client_ip_salt,
)
provider = TracerProvider(
sampler=RecordUnsampled(sampler if sampler is not None else head_sampler_from_env()),
Expand Down
85 changes: 84 additions & 1 deletion adapters/python/redact.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,17 @@
agent, the host's id and addresses, the command line and its owner:
:data:`IDENTIFYING_ATTRIBUTE_KEYS`) are dropped rather than scrubbed:
:func:`drop_identifying_attributes`. ``autter_tracing.RedactingSpanExporter``
applies it to every span, also with redaction off.
applies it to every span, also with redaction off. Opt in to a keyed hash of
the client's address instead (``client.address_hash``): :func:`hash_client_ip`.

Stdlib only.
"""

from __future__ import annotations

import hashlib
import hmac
import ipaddress
import re
from collections.abc import Iterable, Mapping
from typing import Any
Expand Down Expand Up @@ -315,3 +319,82 @@ def drop_identifying_attributes(attributes: Any, dropped: frozenset[str] | None
if not any(key in keys for key in attributes):
return attributes
return {key: value for key, value in attributes.items() if key not in keys}


#: Opt-in hashed client IP: the attribute, its length in hex characters, the
#: shortest salt accepted and the environment variables. Same values as
#: @autter/runtime-node and the ingester (``test-vectors/redaction.json``,
#: ``clientIpHash``).
CLIENT_IP_HASH_ATTRIBUTE = "client.address_hash"
CLIENT_IP_HASH_LENGTH = 32
CLIENT_IP_SALT_MIN_LENGTH = 16
HASH_CLIENT_IP_ENV = "AUTTER_HASH_CLIENT_IP"
CLIENT_IP_SALT_ENV = "AUTTER_CLIENT_IP_SALT"

#: Where the client address is read from, first valid wins: ``client.address``
#: and ``http.client_ip`` (from ``X-Forwarded-For`` behind a proxy), then the
#: socket peer, on server spans only (behind a proxy it is the proxy; on a
#: client span it is the server being called).
CLIENT_IP_SOURCE_KEYS = ("client.address", "http.client_ip", "net.peer.ip", "network.peer.address", "net.sock.peer.addr")
CLIENT_IP_CLIENT_KEYS = ("client.address", "http.client_ip")

_IPV4_PORT = re.compile(r"^[\d.]+:\d{1,5}$")
_BRACKETED = re.compile(r"^\[([^\]]+)\](?::\d{1,5})?$")
_IPV4 = re.compile(r"^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$")
_IPV6_CHARS = re.compile(r"^[0-9a-f:.]+$")


def normalize_client_ip(raw: Any) -> str | None:
"""The canonical text of an IP address, or ``None`` when ``raw`` is not
one: the first entry of a comma-separated list, port and brackets
removed, zone id removed, IPv6 lower-cased and compressed (RFC 5952),
IPv4-mapped IPv6 turned into IPv4."""
if not isinstance(raw, str):
return None
value = raw.split(",")[0].strip()
if not value or len(value) > 100:
return None
bracketed = _BRACKETED.match(value)
if bracketed:
value = bracketed.group(1)
elif _IPV4_PORT.match(value):
value = value[: value.rindex(":")]
if "%" in value:
value = value[: value.index("%")]
value = value.lower()
if _IPV4.match(value):
return value
if ":" not in value or not _IPV6_CHARS.match(value):
return None
try:
address = ipaddress.IPv6Address(value)
except ValueError:
return None
if address.ipv4_mapped is not None:
return str(address.ipv4_mapped)
return address.compressed


def client_ip_of(attributes: Mapping[str, Any] | None, server_span: bool) -> str | None:
"""The normalised client address of a span or log record: the first
:data:`CLIENT_IP_SOURCE_KEYS` entry holding a valid IP (the peer keys
only when ``server_span``)."""
if not attributes:
return None
for key in CLIENT_IP_SOURCE_KEYS if server_span else CLIENT_IP_CLIENT_KEYS:
ip = normalize_client_ip(attributes.get(key))
if ip:
return ip
return None


def usable_client_ip_salt(salt: Any) -> str | None:
"""``salt`` when it is a string of at least :data:`CLIENT_IP_SALT_MIN_LENGTH` characters."""
return salt if isinstance(salt, str) and len(salt) >= CLIENT_IP_SALT_MIN_LENGTH else None


def hash_client_ip(salt: str, ip: str) -> str:
"""HMAC-SHA256(salt, ip) as hex, first :data:`CLIENT_IP_HASH_LENGTH`
characters. ``ip`` is normalised (:func:`normalize_client_ip`). Never
call it without a secret salt: the IPv4 space can be hashed in full."""
return hmac.new(salt.encode("utf-8"), ip.encode("utf-8"), hashlib.sha256).hexdigest()[:CLIENT_IP_HASH_LENGTH]
Loading
Loading