feat(filters): Logs Ingestion API for the time token tracker (2.7.0)

[owndev]

Problem

time_token_tracker.py sends one record per response through the HTTP Data Collector API (workspace shared key). Microsoft ended support for it on September 14, 2026. Ingestion still works with TLS 1.2+, but the API gets no fixes and does not work with Azure Monitor Private Link (AMPLS). The replacement is the Logs Ingestion API: it is based on a data collection rule (DCR) and authenticates with a Microsoft Entra ID token.

Change (Time Token Tracker 2.6.2 → 2.7.0)

• New mode valve LOG_ANALYTICS_INGESTION_API: auto (default) | logs_ingestion | data_collector | both.

  • With auto, records go to the Logs Ingestion API once its settings are complete. Otherwise they go through the Data Collector API exactly as in 2.6.2: same request, signature and headers, plus a one-time deprecation warning.
  • both writes each record to both APIs for a side-by-side migration. One failing side does not stop the other.

• New valves, all with environment-variable defaults:

  • LOG_ANALYTICS_DCR_ENDPOINT, LOG_ANALYTICS_DCR_IMMUTABLE_ID, LOG_ANALYTICS_DCR_STREAM_NAME (derived from LOG_ANALYTICS_LOG_TYPE when empty);
  • LOG_ANALYTICS_AUTH_MODE, LOG_ANALYTICS_TENANT_ID, LOG_ANALYTICS_CLIENT_ID;
  • LOG_ANALYTICS_CLIENT_SECRET (EncryptedStr, password input);
  • LOG_ANALYTICS_AUTHORITY_HOST and LOG_ANALYTICS_INGESTION_SCOPE, for sovereign clouds.

  No valve is renamed or removed. LOG_ANALYTICS_LOG_TYPE can now also be set by environment variable; an empty variable counts as unset.

• Tokens need no extra packages (aiohttp only):

  • client secret;
  • managed identity on App Service / Functions / Container Apps (IDENTITY_ENDPOINT) and on VMs (IMDS);
  • AKS workload identity (federated token file).

  Tokens are cached per identity and refreshed before they expire. Concurrent records share one token request, and a failed refresh keeps using the still-valid token. After a failed token request, or after repeated 401s with fresh tokens, new token requests pause for 30 s. The authority and the endpoint must use https.

• Sending:

  • still in the background with a 10 s timeout (5 s to connect), so answers never wait;
  • any 2xx counts as success (the API answers 204);
  • 400, 401, 403, 404, 413 and 429 are logged once each with an actionable hint (role assignment, DCR ID, stream name, 1 MB limit, Retry-After);
  • no retries, as before.

• Secrets: the client secret is decrypted only for the token request. The secret and the token never appear in logs, status events or error texts. Token errors are redacted before they are cut.

• Docs (docs/setup-azure-log-analytics.md):

  • choosing the API;
  • a Logs Ingestion setup: permissions, the values to collect, checking the existing table with getschema;
  • Option A, migrate OpenWebuiMetrics_CL in place, with a DCR whose transformKql keeps the existing suffixed columns, so Power BI and saved queries keep working. Migration is irreversible; this is called out;
  • Option B, a new table side by side;
  • identity and role assignment (Monitoring Metrics Publisher), DCE and private link, sovereign clouds, troubleshooting.

  README and the docstring are updated as well.

• E2E (filters suite, 57 → 101 checks):

  • mock_la.py now emulates the token endpoint, the managed-identity endpoints and the DCR ingestion endpoint (Bearer check, URI, body, 204, error injection).
  • The new ingest group covers mode selection, the fallback, both, token caching and refresh, the back-off, managed identity, every HTTP error, slow or hanging endpoints, and no secrets in the logs. That last check also covers DEBUG output, which the probe pipe now captures.

Verification

Merging main (#195, Azure 3.0.0) needed two test-harness changes: the managed-identity mock moved from port 9106 to 9107, because 9106 is now the Azure AI Search mock, and the ingest group gives the container its IDENTITY_ENDPOINT/IDENTITY_HEADER back when it ends, so a later azure suite in the same container keeps its managed identity. The filter itself is unchanged.

Run	Result
ruff 0.11.10 check + format	clean
Filters suite, v0.11.4-slim and v0.11.3-slim, normal and --strict-known	101 PASS, 0 FAIL, 0 KNOWN (each)
All suites, v0.11.4-slim, --strict-known	335 PASS, 0 FAIL, 1 KNOWN (infomaniak-name-prefix, no fix yet)
After merging main 4b80e24 (#195): all suites, v0.11.4-slim, normal and --strict-known	462 PASS, 0 FAIL, 1 KNOWN (infomaniak-name-prefix), 463 checks
After merging main: filters + azure, v0.11.3-slim, --strict-known	299 PASS, 0 FAIL, 0 KNOWN
Meta-test (E2E_MOCK_FAULT=500)	0 KNOWN
Mutation testing	first round: 13 surviving mutants found, the tests extended. Each was then rebuilt and killed by its new check

Before the code was written, the API facts were checked against Microsoft Learn, the azure-rest-api-specs and the SDK sources, and a critic reviewed the spec.

Three reviews followed (API and docs, security and compatibility, mutation testing). All 18 findings were fixed, 7 of them major.

Not verified against a real Azure tenant

• the exact x-ms-error-code values;
• which columns an existing OpenWebuiMetrics_CL really has (_g vs _s, timestamp_t). The docs tell users to check with getschema before writing the DCR;
• the App Service / Container Apps token error shape. The mock follows User Managed Identity unable to get tokens - Unable to load the proper Managed Identity microsoft/azure-container-apps#442.

Closes #188

🤖 Generated with Claude Code

[owndev]

Converted to draft: per maintainer decision this becomes Time Token Tracker 3.0.0 with the Logs Ingestion API only. The HTTP Data Collector path and its valves are removed; users who need it stay on 2.6.2. The rework is in progress; the description will be updated when it is ready.

[owndev]

Update: the 3.0.0 rework was stopped before any code change. This PR stays 2.7.0, backward compatible: Microsoft ended support for the HTTP Data Collector API but ingestion still works and no shutdown date is announced, and the both mode allows a safe side-by-side migration. Removing the Data Collector path is tracked in a follow-up issue (remove in 3.0.0 once Microsoft announces a shutdown date). The branch now also contains main (Azure 2.8.1, #190); the conflict in docs/testing.md is resolved.