Skip to content

Add IntentIQ Identity Module - #4915

Open
ykholm wants to merge 1 commit into
prebid:masterfrom
ykholm:iiq-identity-module
Open

Add IntentIQ Identity Module#4915
ykholm wants to merge 1 commit into
prebid:masterfrom
ykholm:iiq-identity-module

Conversation

@ykholm

@ykholm ykholm commented Aug 19, 2026

Copy link
Copy Markdown

Summary

Adds a new host module, intentiq.identity — a Go port of the prebid-server-java
extra/modules/intentiq-identity module. It enriches OpenRTB requests with
IntentIQ-resolved identity and, optionally, reports winning bids to IntentIQ.

What it does

  • processed_auction_request — calls the IntentIQ Bid Enhancement S2S API
    (ProfilesEngineServlet) and merges the resolved eids into user.eids before the
    request reaches bidders. Fail-open: any resolution error leaves the request untouched.
  • auction_response (optional) — fire-and-forget impression report of each winning
    bid to the configured reports_endpoint. The bid response is never modified.
  • Two-layer alias cache (opt-in) — in-process L1 (freecache, byte-bounded) backed by
    a shared L2. Three L2 providers: Redis, Valkey, Aerospike. Includes multi-key
    aliasing with back-fill, negative caching, and in-progress dedup of concurrent
    resolutions.
  • Per-request tracing (opt-in via trace_enabled) — emits the full flow trace
    (cache result and layer, S2S latency and status, eids added) into
    ext.trace.iiq-identity for requests that send ext.prebid.debug.
  • Metrics — per-partner Prometheus counters/histograms/gauges, registered via a new
    moduledeps.ModuleDeps.MetricsRegisterer and exported on the server's existing
    /metrics endpoint.
  • Account-level configpartner_id and timeout can be overridden per account;
    cache and metrics settings are host-global.

Framework changes

Hook modules are built before the metrics engine (which needs moduleStageNames from
that build), so a module's collectors cannot go into the core Prometheus registry. These
four changes give modules a dedicated registry that the existing scrape handler also
gathers from:

  • modules/moduledeps — new MetricsRegisterer prometheus.Registerer field. Nil-safe: a
    module treats a nil registerer as a no-op.
  • router/router.go — creates the module registry, but only when the Prometheus listener
    will actually run (metrics.prometheus.port != 0).
  • metrics/config/metrics.go — carries the gatherer on DetailedMetricsEngine.
  • server/prometheus.go — serves prometheus.Gatherers{core, modules}.
  • modules/builder.go — registers intentiq.identity.

Config & docs

  • modules/intentiq/identity/README.md — overview, setup/execution plan, parameters,
    caching and all three L2 backends, impression reporting, tracing, metrics, demo.
  • sample/002_intentiq_identity/ — runnable sample (app.yaml, request.json,
    stored_response.json) wired into sample/docker-compose.yml alongside a Valkey
    service, per the existing sample/ convention.

Testing

  • Unit and integration tests for every component: both hooks, key extraction, UA
    normalization, the two-layer cache (miniredis for Redis; test doubles for Valkey and
    Aerospike), metrics, config merge, builder/shutdown, and tracing.
  • go build ./..., go vet ./..., and gofmt clean. ./validate.sh --nofmt --cov --race 10
    passes. Module tests also pass under go test -race.
  • Coverage: identity 94.6%, cache 90.4%, cache/provider 92.3%, aerospike 92.2%,
    valkey 100%, memory 89.1%, redis 85.7%, enrichment 93.8%, metrics 94.4%.

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