Skip to content

Usage Tracking

The AI Context module tracks how context items are used by consumers, giving you visibility into which items are being selected and where.

!!! note "Future observability integration" Usage tracking is intentionally lightweight for now. AI observability will be integrated later, which will replace the current functionality.

Usage tracking is disabled by default. Enable it at /admin/config/ai/context/settings/usage when you want lightweight observability into which context items consumers select.

Access and redaction

Usage pages require View AI Context Usage. That permission alone does not allow viewing linked context items, their content, or target entities the user cannot otherwise access.

Listing and detail views redact inaccessible context items and target entities (for example Context item {id} (no access)). See Access boundaries for the full model.

How it works

When a consumer runs and context is selected, the module records:

  • Which context items were included in the prompt
  • Which consumer used them (consumer_id plus derived consumer_type)
  • The runner ID when the consumer has one (agent runs). Generic chat injection records NULL because those requests have no runner.
  • The route/path where the consumer was triggered
  • Which tools were used during an agent run
  • Which entities were created or modified

Usage records are stored as ai_context_usage entities.

!!! note "Database indexes" The context_item_id field is an entity reference, so Drupal creates its target ID index automatically. In raw database output, this index may appear with a generated hashed name such as ai_context_usage__0ca4136628.

The module also adds explicit indexes for `runner_id`, `changed`,
`(entity_item_type, entity_item_id)`, and
`(context_item_id, consumer_id)`.

Viewing usage data

Usage listing

Go to /admin/config/ai/context/usage to see a Views-based listing of all usage records. The listing shows which context items were used, by which consumers, and when.

Usage record detail

Click on any usage record to see its full details at /admin/config/ai/context/usage/{id}, including:

  • The consumer that ran
  • The context items that were selected
  • The route where it happened
  • Tools used during execution
  • Entities that were created or modified

Usage settings

Configure usage tracking at /admin/config/ai/context/settings/usage:

  • Enable/disable usage tracking
  • Maximum records -- cap the total number of usage records stored
  • Maximum age -- automatically purge records older than a configured duration

Automatic cleanup

Old usage records are purged during cron based on the configured limits:

  • Records older than the maximum age are deleted first
  • If the total count still exceeds the maximum records setting, the oldest excess records are removed

Clearing usage data

To manually clear all usage records, go to /admin/config/ai/context/settings/usage/clear and confirm the deletion.