Skip to content

Opt-in hashed client IP (client.address_hash), stacked on #51 - #52

Merged
sagnik11 merged 5 commits into
mainfrom
fix/hash-client-ip
Nov 14, 2026
Merged

sagnik11 merged 5 commits into
mainfrom
fix/hash-client-ip

Conversation

@sagnik11

@sagnik11 sagnik11 commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Stacked on #51 (base branch fix/drop-identifying-attributes). Merge #51 first. GitHub then retargets this PR to main.

What was wrong

#51 drops the client IP address from every span. That is the right default, but it also takes away any way to count distinct clients. This PR adds an opt-in keyed hash of the address.

What changed

When hashing is on, the client's address is exported only as client.address_hash. The value is HMAC-SHA256 of the normalised address under a secret salt, cut to the first 32 hex characters (128 bits). The raw address is still dropped.

  • Turning it on:
    • @autter/runtime-node: hashClientIp: true (salt from AUTTER_CLIENT_IP_SALT) or hashClientIp: { salt }. It also works through registerAutter.
    • Python adapter: init_tracing(hash_client_ip=True, client_ip_salt=...) or RedactingSpanExporter(..., hash_client_ip=, client_ip_salt=).
    • Env for both SDKs and the ingester: AUTTER_HASH_CLIENT_IP=true with AUTTER_CLIENT_IP_SALT.
  • Off by default. If hashing is on but there is no salt of at least 16 characters, nothing is hashed and one warning is printed. There is never an unsalted fallback, because every IPv4 address can be hashed in minutes. The salt stays in a closure and is never logged, exported or written to an attribute. The tests check that it appears neither in exported bodies nor on stderr.
  • Which address is hashed: the first valid one of client.address, then http.client_ip (both filled from X-Forwarded-For / Forwarded behind a proxy), then the socket peer (net.peer.ip, network.peer.address, net.sock.peer.addr). The socket peer is read on server spans only: behind a proxy it is the proxy, and on a client span it is the server being called.
  • Normalisation: take the first entry of a comma-separated list, strip the port, brackets and zone id, lower-case and compress IPv6 (RFC 5952), and turn IPv4-mapped IPv6 into IPv4. Anything that is not an IP is not hashed.
  • Same result everywhere: the same salt and the same IP give the same hash in runtime-core/runtime-node, the Python adapter and the ingester. A new clientIpHash section in test-vectors/redaction.json (normalisation, source order, hashes) is checked by all four test suites.
  • Ingester: it hashes only spans and log records that carry no client.address_hash. A hash sent by an SDK is stored as it is and never hashed again. It logs at startup whether hashing is on, never the salt.
  • Docs: runtime-node README, otlp-ingester README (env rows and a section), docs/ARCHITECTURE.md, docs/INTEGRATIONS.md and the CHANGELOG all say that a hashed IP is still pseudonymous personal data in some readings of privacy law, and that the salt is a secret.

Where the salt comes from

Only from an explicit setting: the option, or AUTTER_CLIENT_IP_SALT. There is no derived default.

  • Deriving it from the ingest key would change every hash when the key is rotated, and would differ between services that use different keys.
  • Deriving it from anything public, such as the service name or repository id, would let another project compute the same hash.

The ingester has one salt for all the projects it serves. The README says that on a shared ingester those hashes are comparable across projects to whoever can read all of them, and recommends hashing in the SDK with a per-project salt.

How to test

  • node --test packages/runtime-core/test/client-ip.test.mjs (after npm run build -w @autter/runtime-core)
  • cd packages/runtime-node && node --test test/client-ip-hash.test.mjs. This runs child processes with real HttpInstrumentation and X-Forwarded-For, and covers: off by default, { salt }, env together with redactAttributes: false, no salt (exactly one warning, nothing hashed), a hash already on the span kept, no hash on client spans, and the salt never on the wire or on stderr.
  • cd packages/otlp-ingester && npx tsx --test src/client-ip-hash.test.ts. This covers the vectors, the filter, and a real Python Flask protobuf export through the ingester with and without a salt.
  • python3 -m unittest discover -s adapters/python -v (test_client_ip_hash.py).

Not covered

  • Nothing in the dashboard or the platform reads client.address_hash yet.
  • The ingester has no per-project salt. On a multi-tenant ingester, hash in the SDK instead.
  • The browser SDK and the relay are unchanged. They never send a client IP.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

sagnik11 and others added 5 commits November 15, 2026 02:32
OpenTelemetry puts the client's IP address and port, the raw user agent,
the machine's id and addresses, and the command line and its owner on
every server span and on the resource. Redaction kept them (none looks
like a secret) and nothing in Autter reads them.

One list (runtime-core identifying.ts, mirrored in adapters/python
redact.py and otlp-ingester identifying.ts, parity through
test-vectors/redaction.json) is now dropped:

- runtime-node: at export from span, event and link attributes and the
  span and metric resources, also with redactAttributes: false;
- Python adapter: in RedactingSpanExporter (also with redact=False) and
  on init_tracing()'s resource;
- otlp-ingester: on arrival for traces, logs (attributes and structured
  body keys) and metric resources, so plain OTel senders and old SDKs
  are covered.

service.instance.id, host.name, process.pid, process.runtime.*, os.type
and host.arch are kept. keepIdentifyingAttributes /
keep_identifying_attributes / AUTTER_KEEP_IDENTIFYING_ATTRIBUTES keep
them (true or a list; needed on both SDK and ingester), and
dropAttributes / drop_attributes / AUTTER_DROP_ATTRIBUTES drop more keys
such as host.name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
hashClientIp (runtime-node), hash_client_ip (Python adapter) and
AUTTER_HASH_CLIENT_IP (SDKs and ingester), with a secret salt
(AUTTER_CLIENT_IP_SALT, 16+ characters), add client.address_hash:
HMAC-SHA256 of the normalised client address, 32 hex characters. The raw
address is still dropped.

- Source order: client.address, http.client_ip, then on server spans the
  socket peer (net.peer.ip, network.peer.address, net.sock.peer.addr).
- Normalisation: first list entry, port, brackets and zone id removed,
  IPv6 compressed and lower-cased, IPv4-mapped IPv6 read as IPv4.
- Off by default. On without a usable salt: nothing hashed, one warning,
  never an unsalted hash. The salt is never logged or exported.
- The ingester hashes only spans and log records without a hash and never
  re-hashes one.
- Shared vectors (test-vectors/redaction.json, clientIpHash) checked by
  runtime-core, runtime-node, the Python adapter and the ingester.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…attributes

# Conflicts:
#	CHANGELOG.md
#	adapters/python/autter_tracing.py
… into fix/hash-client-ip

# Conflicts:
#	adapters/python/autter_tracing.py
…erged here)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sagnik11
sagnik11 changed the base branch from fix/drop-identifying-attributes to main November 14, 2026 23:49
@sagnik11
sagnik11 merged commit d5ee510 into main Nov 14, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant