README

Enriches OpenTelemetry SERVER spans with end-user identity — device id, session id, client address — for a PHP app that already has OpenTelemetry auto-instrumentation running (CodeIgniter 4, Laravel, Slim, Symfony, any PSR-15 app). No code changes in your app. composer require it and it wires itself in through Composer's files autoload.

The companion browser package sends baggage: app.device.id=<uuid>,session.id=<uuid> on every same-origin fetch/XHR, which is how the identity gets from the browser to your PHP server in the first place.

Prerequisites

• PHP >=8.1
• ext-opentelemetry (the OpenTelemetry PHP extension) enabled
• open-telemetry/sdk and an auto-instrumentation package for your framework already installed and working — i.e. you already see SERVER spans for your requests without this package. This package only adds attributes to spans that already exist; it does not create a tracer, exporter or instrumentation on its own.

Install

composer require netident/otel-enduser

Without internet access

A host that cannot reach Packagist installs the same package from your NETiDENT platform: download the zip and point Composer at it with an artifact repository:

mkdir -p ./netident-sdk
curl -fsSL -o ./netident-sdk/netident-otel-enduser-0.1.2.zip \
  https://<your-platform-host>/sdk/netident-otel-enduser-0.1.2.zip

{
    "repositories": [
        { "type": "artifact", "url": "./netident-sdk" }
    ]
}

composer require netident/otel-enduser

Where the ids come from

This package only reads an id that arrives with the request — it cannot tell two browsers apart on its own. Something has to create the ids:

• The NETiDENT browser script (rum.js / @netident/rum) on your pages. It sends them as baggage on fetch/XHR and keeps them in the _nid_dev / _nid_ses cookies, which is what a page load or a form post carries. It also gives you real-user page data (Web Vitals, JS errors), and honours its consent mode.
• This package itself, with NETIDENT_ISSUE_COOKIES=true — for an app that renders its own pages and runs no browser script. See below.

Without a browser script

With NETIDENT_ISSUE_COOKIES=true, a browser page load (Sec-Fetch-Dest: document, or Accept: text/html from a browser without Fetch Metadata) that arrives without _nid_dev / _nid_ses gets them minted and set on the response (path=/, SameSite=Lax, Secure on https, not HttpOnly so the browser script can continue the same ids). The session cookie is re-set on every page load and expires 15 minutes after the last one. That request's own span already carries the new ids (app.device.id.source=issued); later requests send the cookies back.

Things to know before turning it on:

• It sets an identifying cookie without asking for consent. If your site must ask first (PDPA / GDPR), leave it off and use the browser script's consent mode instead.
• Page-load responses carry Set-Cookie, which most CDNs and reverse-proxy caches treat as uncacheable.
• API clients, curl and health checks are never issued a cookie — they would not keep it, and every request would become a new "device".
• Needs a classic request-per-process runtime (php-fpm, mod_php). Worker runtimes (Swoole, RoadRunner, Octane) do not populate $_SERVER / $_COOKIE per request, which this package reads.

Environment variables

Standard OpenTelemetry variables are also honoured: setting OTEL_PHP_DISABLED_INSTRUMENTATIONS to a comma list containing netident-enduser or all disables this package the same way any other auto-instrumentation is disabled.

Linking page loads and API calls to traces

Every request whose SERVER span is sampled gets a response header:

Server-Timing: traceparent;desc="00-<32 hex trace id>-<16 hex span id>-01"

This is on by default — set NETIDENT_SERVER_TIMING=off to stop it. The NETiDENT browser script reads it from the page's navigation-timing entry and from every fetch/XHR's resource-timing entry, which is how a page load — and every API call it makes, sampled or not — gets linked to its backend trace. It names the trace only: no timings, no user data, and it never replaces a Server-Timing value your app already sends (added with header(..., false), so existing values are kept).

If the page calling your API is on a different origin, the browser only exposes Server-Timing to that page's script when your API's response also sends Timing-Allow-Origin: https://<page origin> (or *). A same-origin call needs nothing extra.

Verify

Send a request with a baggage header, e.g.:

curl -H 'baggage: app.device.id=test-device-1,session.id=test-session-1' \
  https://your-app.example/some/route

Then look at the SERVER span for that request in your tracing backend — it should carry app.device.id=test-device-1, app.device.id.source=baggage and session.id=test-session-1, plus client.address.

Disable

Set NETIDENT_ENDUSER_DISABLED=true, or add netident-enduser (or all) to OTEL_PHP_DISABLED_INSTRUMENTATIONS.

Non-browser clients

A mobile app, a service-to-service call, or any client that cannot send a baggage header can instead send the device id in a plain X-Device-Id header — it is used whenever no baggage member is present.

License

Apache-2.0 — see LICENSE.