---
title: "View source for AI Services/AI Gateway - DreamFactory Wiki"
source: "https://wiki.dreamfactory.com/index.php?action=edit&title=AI_Services%2FAI_Gateway"
canonical_url: "https://wiki.dreamfactory.com/index.php?action=edit&title=AI_Services%2FAI_Gateway"
converted_at: "2026-11-22T23:03:08.285Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
	
	
	
	# View source for AI Services/AI Gateway

	
		
		← [AI Services/AI Gateway](/AI_Services/AI_Gateway)
		
		
		
		[Jump to navigation](#mw-head)
		[Jump to search](#searchInput)
		You do not have permission to edit this page, for the following reason:

The action you have requested is limited to users in the group: [Users](/index.php?title=DreamFactory_Wiki:Users&action=edit&redlink=1).---

You can view and copy the source of this page.

{{#seo:
|title=AI Gateway Analytics - DreamFactory Documentation
|title_mode=replace
|description=Monitor AI spend, track per-app attribution, view latency percentiles, configure budgets, enable prompt logging, and export audit events to your SIEM.
|keywords=DreamFactory, AI Gateway, analytics, cost tracking, usage dashboard, prompt logging, SIEM, audit, budget, rate limiting, latency
|canonical=https://wiki.dreamfactory.com/AI_Services/Ai_Gateway
|og:title=AI Gateway Analytics
|og:type=article
|og:site_name=DreamFactory Documentation
|og:description=Monitor AI spend, track per-app attribution, view latency percentiles, configure budgets, enable prompt logging, and export audit events to your SIEM.
}}
'''Monitor AI spend, track per-app attribution, view latency percentiles, configure budgets, enable prompt logging, and export audit events to your SIEM.'''

&lt;span id="ai-gateway-analytics">&lt;/span>
== AI Gateway Analytics ==

DreamFactory's AI Gateway provides org-wide visibility into AI usage, cost, and performance. Every request through an AI Connection (direct API calls, AI Chat sessions, and OpenAI-compatible endpoint traffic) is logged with full attribution: which user, role, app, provider, model, and service handled the request, along with token counts, cost, latency, and status.

The Gateway analytics are available through admin API endpoints and power the admin dashboard's AI section.

{{Note|AI Gateway Analytics requires a DreamFactory commercial license (Gold or Platinum).}}

&lt;span id="usage-logging">&lt;/span>
== Usage Logging ==

Every AI provider call writes a row to the &lt;code>ai_usage_log&lt;/code> table with:

{| class="wikitable"
|-
! '''Column'''
! '''Description'''
|-
| &lt;code>service_id&lt;/code>
| Which AI Connection handled the request
|-
| &lt;code>user_id&lt;/code>
| The DreamFactory user who made the request
|-
| &lt;code>role_id&lt;/code>
| The role in effect
|-
| &lt;code>app_id&lt;/code>
| The application (API key) used
|-
| &lt;code>resource&lt;/code>
| Request type: &lt;code>chat&lt;/code>, &lt;code>completion&lt;/code>, &lt;code>chat-session&lt;/code>, &lt;code>data-chat&lt;/code>, &lt;code>openai_compat&lt;/code>
|-
| &lt;code>provider&lt;/code>
| Upstream provider (&lt;code>anthropic&lt;/code>, &lt;code>openai&lt;/code>, &lt;code>xai&lt;/code>, &lt;code>ollama&lt;/code>, &lt;code>openai_compatible&lt;/code>)
|-
| &lt;code>model&lt;/code>
| Model used (e.g. &lt;code>gpt-4o&lt;/code>, &lt;code>claude-sonnet-4-5-20250929&lt;/code>)
|-
| &lt;code>input_tokens&lt;/code>
| Tokens consumed in the request
|-
| &lt;code>output_tokens&lt;/code>
| Tokens generated in the response
|-
| &lt;code>cost_usd&lt;/code>
| Estimated cost in USD (computed at log time from per-model rates, service rates, or provider defaults)
|-
| &lt;code>latency_ms&lt;/code>
| Round-trip time in milliseconds
|-
| &lt;code>tool_call_count&lt;/code>
| Number of tool calls in agentic loops
|-
| &lt;code>status&lt;/code>
| &lt;code>success&lt;/code>, &lt;code>partial&lt;/code> (streaming disconnect), or &lt;code>error&lt;/code>
|-
| &lt;code>error_message&lt;/code>
| Error details (for failed requests)
|-
| &lt;code>request_id&lt;/code>
| UUID correlating usage, prompt log, and audit events
|}

&lt;span id="status-types">&lt;/span>
=== Status Types ===

* '''success''': The provider returned a complete response.
* '''partial''': A streaming request where the client disconnected before completion. Tokens consumed up to the disconnect are still counted.
* '''error''': The provider returned an error or the connection failed. Cost is zero for error rows.

&lt;span id="analytics-dashboard-api">&lt;/span>
== Analytics Dashboard API ==

'''&lt;code>GET /_internal/ai/usage&lt;/code>''' (admin only)

Returns the full analytics payload for the dashboard. Supports filtering and period-over-period comparison.

&lt;span id="query-parameters">&lt;/span>
=== Query Parameters ===

{| class="wikitable"
|-
! '''Parameter'''
! '''Default'''
! '''Description'''
|-
| &lt;code>period&lt;/code>
| &lt;code>7d&lt;/code>
| Time window: &lt;code>24h&lt;/code>, &lt;code>7d&lt;/code>, &lt;code>30d&lt;/code>, &lt;code>90d&lt;/code>, or any &lt;code>{n}d&lt;/code> / &lt;code>{n}h&lt;/code> format
|-
| &lt;code>compare&lt;/code>
| &lt;code>0&lt;/code>
| Set to &lt;code>1&lt;/code> to include a &lt;code>previous&lt;/code> block with the same metrics for the immediately preceding window
|-
| &lt;code>provider&lt;/code>
|
| Filter by provider name
|-
| &lt;code>service_id&lt;/code>
|
| Filter by AI Connection service ID
|-
| &lt;code>model&lt;/code>
|
| Filter by model name
|-
| &lt;code>user_id&lt;/code>
|
| Filter by user ID
|-
| &lt;code>role_id&lt;/code>
|
| Filter by role ID
|-
| &lt;code>app_id&lt;/code>
|
| Filter by app ID
|-
| &lt;code>resource&lt;/code>
|
| Filter by resource type
|-
| &lt;code>status&lt;/code>
|
| Filter by status
|}

&lt;span id="response-shape">&lt;/span>
=== Response Shape ===

&lt;syntaxhighlight lang="json">{
  "period": "7d",
  "since": "2026-05-25T00:00:00+00:00",
  "total_requests": 15420,
  "total_input_tokens": 2345670,
  "total_output_tokens": 890120,
  "total_cost_usd": 47.23,
  "errors": 31,
  "partials": 8,
  "avg_latency_ms": 1340,
  "latency_p50_ms": 980,
  "latency_p95_ms": 3200,
  "latency_p99_ms": 8500,
  "by_service": ["..."],
  "by_user": ["..."],
  "by_role": ["..."],
  "by_app": ["..."],
  "by_provider": ["..."],
  "by_model": ["..."],
  "by_resource": ["..."],
  "by_error_class": ["..."],
  "series": ["..."],
  "series_by_model": ["..."],
  "series_by_user": ["..."],
  "series_by_app": ["..."],
  "series_by_provider": ["..."],
  "most_expensive_calls": ["..."],
  "budgets": ["..."],
  "default_rates": {},
  "filters": {}
}&lt;/syntaxhighlight>

&lt;span id="key-sections">&lt;/span>
=== Key Sections ===

'''Latency percentiles''' (&lt;code>latency_p50_ms&lt;/code>, &lt;code>latency_p95_ms&lt;/code>, &lt;code>latency_p99_ms&lt;/code>): Cross-database compatible. Useful for identifying whether latency issues affect the median user or just tail requests.

'''By-model breakdown''' (&lt;code>by_model&lt;/code>): Includes &lt;code>cost_per_1k_tokens&lt;/code> for each model, showing the effective rate you are paying. Helps answer "is this premium model worth its rate?"

'''Error classification''' (&lt;code>by_error_class&lt;/code>): Errors are automatically classified into categories: &lt;code>timeout&lt;/code>, &lt;code>rate_limit&lt;/code>, &lt;code>auth&lt;/code>, &lt;code>model_not_found&lt;/code>, &lt;code>context_overflow&lt;/code>, &lt;code>connectivity&lt;/code>, &lt;code>provider_5xx&lt;/code>, &lt;code>provider_4xx&lt;/code>, &lt;code>other&lt;/code>. Helps identify whether an error spike is a rate-limit problem or a provider outage.

'''Time series''' (&lt;code>series&lt;/code>, &lt;code>series_by_model&lt;/code>, &lt;code>series_by_user&lt;/code>, &lt;code>series_by_app&lt;/code>, &lt;code>series_by_provider&lt;/code>): Daily-bucketed cost-over-time breakdowns. The &lt;code>series_by_*&lt;/code> variants show top-10 spenders plus an &lt;code>__other__&lt;/code> bucket so stacked charts don't silently undercount.

'''Most expensive calls''' (&lt;code>most_expensive_calls&lt;/code>): Top 10 costliest individual requests in the window. Surfaces outliers (e.g. a single 200K-token request) that averages hide.

'''Period comparison''' (when &lt;code>compare=1&lt;/code>): The &lt;code>previous&lt;/code> block contains the same summary metrics (totals, percentiles) for the window immediately before the current one. Powers period-over-period delta indicators.

&lt;span id="budget-management">&lt;/span>
== Budget Management ==

&lt;span id="per-service-monthly-budgets">&lt;/span>
=== Per-Service Monthly Budgets ===

Set &lt;code>monthly_budget_usd&lt;/code> on an AI Connection to enable spend projection. The dashboard's &lt;code>budgets&lt;/code> array returns:

&lt;syntaxhighlight lang="json">{
  "service_id": 5,
  "monthly_budget_usd": 500.00,
  "spent_month_usd": 187.42,
  "projected_month_end_usd": 374.84,
  "days_into_month": 15,
  "days_in_month": 30,
  "on_track": true
}&lt;/syntaxhighlight>

Services are sorted by risk (highest projected overshoot first).

&lt;span id="multi-dimensional-budget-rules">&lt;/span>
=== Multi-Dimensional Budget Rules ===

For fine-grained control, create rows in the &lt;code>ai_budget&lt;/code> table:

{| class="wikitable"
|-
! '''Field'''
! '''Description'''
|-
| &lt;code>dimension_type&lt;/code>
| &lt;code>global&lt;/code>, &lt;code>service&lt;/code>, &lt;code>user&lt;/code>, &lt;code>role&lt;/code>, or &lt;code>app&lt;/code>
|-
| &lt;code>dimension_id&lt;/code>
| The ID of the target entity (null for global)
|-
| &lt;code>period&lt;/code>
| &lt;code>hourly&lt;/code>, &lt;code>daily&lt;/code>, or &lt;code>monthly&lt;/code>
|-
| &lt;code>budget_usd&lt;/code>
| Spend cap in USD
|-
| &lt;code>hard_stop&lt;/code>
| When &lt;code>true&lt;/code>, requests are blocked (HTTP 429) once the cap is reached
|-
| &lt;code>alert_webhook_url&lt;/code>
| URL to receive threshold-crossing notifications
|-
| &lt;code>alert_webhook_auth_header&lt;/code>
| Optional &lt;code>Authorization&lt;/code> header for the webhook
|-
| &lt;code>label&lt;/code>
| Human-readable label for alerts
|}

&lt;span id="budget-alerts">&lt;/span>
=== Budget Alerts ===

When a budget crosses 50%, 80%, or 100% utilization, the configured webhook fires with a structured payload:

&lt;syntaxhighlight lang="json">{
  "event": "ai.budget.threshold_crossed",
  "threshold_pct": 80,
  "budget": {
    "id": 3,
    "label": "Engineering team monthly",
    "dimension_type": "role",
    "dimension_id": 7,
    "period": "monthly",
    "budget_usd": 1000.00,
    "hard_stop": false
  },
  "spend": {
    "spend_usd": 812.45,
    "remaining_usd": 187.55,
    "utilization": 0.8125
  },
  "@timestamp": "2026-06-01T14:30:00+00:00"
}&lt;/syntaxhighlight>

Each threshold fires once per period. Thresholds reset automatically at the start of each new period.

&lt;span id="prompt-logging">&lt;/span>
== Prompt Logging ==

Prompt logging records the full request and response text for AI calls. It is '''off by default''' and must be enabled per AI Connection.

&lt;span id="prompt-logging-configuration">&lt;/span>
=== Configuration ===

Prompt logging is controlled at two levels:

# '''Global kill switch''': Set &lt;code>df-ai.prompt_logging.global_enabled&lt;/code> to &lt;code>false&lt;/code> in the config to disable prompt logging across the entire instance. Use this for deployments that legally cannot store prompts.
# '''Per-connection opt-in''': On each AI Connection, enable these fields (available in the config model):
#* &lt;code>prompt_logging_enabled&lt;/code> (default: false) -- master switch
#* &lt;code>prompt_redact_pii&lt;/code> (default: true) -- apply built-in PII patterns before storage
#* &lt;code>prompt_redaction_rules&lt;/code> -- JSON array of custom regex patterns

&lt;span id="pii-redaction">&lt;/span>
=== PII Redaction ===

When PII redaction is enabled, the following patterns are automatically scrubbed from prompts and responses before storage:

{| class="wikitable"
|-
! '''Pattern'''
! '''Description'''
|-
| Credit card numbers
| 13-19 digit sequences with Luhn validation (reduces false positives)
|-
| SSN
| US Social Security Numbers in 3-2-4 dashed format
|-
| Email addresses
| RFC-5322-ish pattern
|-
| US phone numbers
| NANP format with separators
|-
| Medical Record Numbers
| "MRN" or "Medical Record Number" followed by an alphanumeric ID
|}

These built-in patterns prioritize low false-positive rates over completeness. For comprehensive DLP coverage (passports, driver's licenses, IBANs, etc.), configure custom redaction rules or integrate a cloud DLP service.

&lt;span id="custom-redaction-rules">&lt;/span>
=== Custom Redaction Rules ===

Add custom patterns via the &lt;code>prompt_redaction_rules&lt;/code> field (JSON array):

&lt;syntaxhighlight lang="json">[
  {"pattern": "/\\bACCT-\\d{6,10}\\b/", "label": "ACCOUNT_ID"},
  {"pattern": "/\\bPATIENT-\\w{8}\\b/i", "label": "PATIENT_ID", "replacement": "[REMOVED]"}
]&lt;/syntaxhighlight>

Each rule has:
* &lt;code>pattern&lt;/code>: A PHP regex pattern
* &lt;code>label&lt;/code> (optional): The label used in the replacement placeholder. Default: &lt;code>CUSTOM&lt;/code>
* &lt;code>replacement&lt;/code> (optional): Custom replacement text. Default: &lt;code>[REDACTED:{label}]&lt;/code>

&lt;span id="prompt-log-schema">&lt;/span>
=== Prompt Log Schema ===

Logged prompts are stored in &lt;code>ai_prompt_log&lt;/code> with:

{| class="wikitable"
|-
! '''Column'''
! '''Description'''
|-
| &lt;code>request_id&lt;/code>
| Correlates to the &lt;code>ai_usage_log&lt;/code> row for the same call
|-
| &lt;code>service_id&lt;/code>
| AI Connection service ID
|-
| &lt;code>user_id&lt;/code>, &lt;code>role_id&lt;/code>, &lt;code>app_id&lt;/code>
| Attribution
|-
| &lt;code>provider&lt;/code>, &lt;code>model&lt;/code>, &lt;code>resource&lt;/code>
| Request metadata
|-
| &lt;code>request_payload&lt;/code>
| Redacted request text
|-
| &lt;code>response_payload&lt;/code>
| Redacted response text
|-
| &lt;code>redaction_count&lt;/code>
| Total PII replacements made (for "what % of traffic triggers redaction" analytics)
|-
| &lt;code>original_size_bytes&lt;/code>
| Pre-redaction payload size
|-
| &lt;code>status&lt;/code>
| &lt;code>success&lt;/code>, &lt;code>partial&lt;/code>, or &lt;code>error&lt;/code>
|}

&lt;span id="siem-integration">&lt;/span>
== SIEM Integration ==

DreamFactory supports both push-based and pull-based SIEM integration for AI audit events.

&lt;span id="push-webhook-dispatch">&lt;/span>
=== Push: Webhook Dispatch ===

Configure &lt;code>audit_webhook_url&lt;/code> on an AI Connection to push ECS-shaped audit events to your SIEM after every AI call.

{| class="wikitable"
|-
! '''Field'''
! '''Description'''
|-
| &lt;code>audit_webhook_url&lt;/code>
| Endpoint URL for the webhook
|-
| &lt;code>audit_webhook_format&lt;/code>
| Event format: &lt;code>ecs&lt;/code> (default), &lt;code>splunk_hec&lt;/code>, or &lt;code>datadog&lt;/code>
|-
| &lt;code>audit_webhook_auth_header&lt;/code>
| Optional &lt;code>Authorization&lt;/code> header value
|}

Webhook dispatch is best-effort with a 5-second timeout. Failures are logged as warnings but never break the AI response. The &lt;code>ai_usage_log&lt;/code> + &lt;code>ai_prompt_log&lt;/code> tables remain the source of truth.

&lt;span id="push-file-sink">&lt;/span>
=== Push: File Sink ===

Enable &lt;code>audit_file_sink_enabled&lt;/code> on an AI Connection to append NDJSON events to a log file. Default path: &lt;code>/var/log/dreamfactory/ai-audit.log&lt;/code>.

This works well with Logstash's &lt;code>file&lt;/code> input plugin for a zero-configuration SIEM pipeline.

&lt;span id="pull-audit-stream-endpoint">&lt;/span>
=== Pull: Audit Stream Endpoint ===

'''&lt;code>GET /_internal/ai/audit-stream&lt;/code>''' (admin only)

Returns a newline-delimited JSON (NDJSON) stream of ECS-shaped audit events. Designed for Logstash's &lt;code>http_poller&lt;/code> input, Splunk's HTTP input, Datadog HTTP intake, or any pull-based pipeline.

'''Query parameters:'''

{| class="wikitable"
|-
! '''Parameter'''
! '''Default'''
! '''Description'''
|-
| &lt;code>since&lt;/code>
| 5 minutes ago
| ISO-8601 start timestamp
|-
| &lt;code>until&lt;/code>
| now
| ISO-8601 end timestamp
|-
| &lt;code>limit&lt;/code>
| 1000
| Max events (capped at 5000)
|}

'''Response headers:'''

&lt;syntaxhighlight lang="text">Content-Type: application/x-ndjson&lt;/syntaxhighlight>

'''Example Logstash configuration:'''

&lt;syntaxhighlight lang="ruby">input {
  http_poller {
    urls => {
      dreamfactory_ai => {
        url => "https://df.example/_internal/ai/audit-stream?since=&lt;last_max_timestamp>"
        headers => {
          "X-DreamFactory-API-Key" => "your-admin-api-key"
          "X-DreamFactory-Session-Token" => "your-session-token"
        }
      }
    }
    schedule => { cron => "* * * * *" }
    codec => "json_lines"
  }
}&lt;/syntaxhighlight>

&lt;span id="event-formats">&lt;/span>
=== Event Formats ===

All audit events follow the Elastic Common Schema (ECS) base shape. The &lt;code>audit_webhook_format&lt;/code> setting controls the envelope:

* '''&lt;code>ecs&lt;/code>''' (default): Raw ECS event. Works with Elastic/Logstash directly.
* '''&lt;code>splunk_hec&lt;/code>''': Wrapped in Splunk HTTP Event Collector format with &lt;code>event&lt;/code>, &lt;code>time&lt;/code>, &lt;code>source&lt;/code>, &lt;code>sourcetype&lt;/code> fields.
* '''&lt;code>datadog&lt;/code>''': Wrapped in Datadog log intake format with &lt;code>ddsource&lt;/code>, &lt;code>ddtags&lt;/code>, &lt;code>message&lt;/code> fields.

&lt;span id="test-connection">&lt;/span>
== Test Connection ==

'''&lt;code>POST /_internal/ai/test-connection&lt;/code>''' (admin only)

Validates provider credentials before saving a service. Attempts to list models from the provider with the given config. Useful for the admin UI's "Test Connection" button.

'''Request:'''

&lt;syntaxhighlight lang="json">{
  "provider": "anthropic",
  "api_key": "sk-ant-...",
  "service_id": 5
}&lt;/syntaxhighlight>

When &lt;code>service_id&lt;/code> is provided and &lt;code>api_key&lt;/code> is blank, the endpoint falls back to the saved credentials, so admins can test without re-entering secrets.

&lt;span id="cost-calculation">&lt;/span>
== Cost Calculation ==

Cost is computed at log time using a three-tier lookup:

# '''Per-model rate sheet''' on the AI Connection (most specific)
# '''Service-level flat rates''' (&lt;code>cost_per_1k_input&lt;/code>, &lt;code>cost_per_1k_output&lt;/code>)
# '''Built-in provider defaults''' maintained by DreamFactory

Because cost is computed and stored at log time, price changes do not retroactively rewrite historical data.

&lt;span id="data-retention">&lt;/span>
== Data Retention ==

Usage and prompt logs can be pruned via artisan commands:

&lt;syntaxhighlight lang="bash">php artisan ai:prune-usage-logs    # Default retention: 90 days
php artisan ai:prune-prompt-logs&lt;/syntaxhighlight>

Schedule these commands via cron to keep database size manageable in high-volume deployments.

== See also ==
* [[AI_Services/Ai_Connection|AI Connection]]
* [[AI_Services/Ai_Chat|AI Chat]]
* [[AI_Services/Mcp_Service|MCP Server]]

[[Category:Ai_Gateway]]
[[Category:Analytics]]
[[Category:Ai_Integration]]
[[Category:Siem]]
[[Category:Difficulty_Advanced]]
Template used on this page:

- [Template:Note](/Template:Note) ([view source](/index.php?title=Template:Note&action=edit))

Return to [AI Services/AI Gateway](/AI_Services/AI_Gateway).

Retrieved from "[https://wiki.dreamfactory.com/AI_Services/AI_Gateway](https://wiki.dreamfactory.com/AI_Services/AI_Gateway)"