--- title: Audit Trail description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > DDSQL Reference > Data Directory > Audit Trail --- # Audit Trail This dataset represents audit trail events collected by Datadog for compliance and security monitoring. It tracks all access and configuration activity by users and through APIs across the Datadog Platform, providing detailed audit events for user actions, authentication methods, API calls, and system changes. This enables organizations to monitor who is using Datadog, investigate security incidents, and maintain compliance tracking with full integration into Datadog alerts, dashboards, and role-based access control. ``` dd.audit ``` Audit Trail Public Documentation {% icon name="icon-external-link" /%} Audit Logging Knowledge Center {% icon name="icon-external-link" /%} ## Query Parameters This dataset uses a **polymorphic table function**. You must specify parameters when querying. | Parameter | Type | Required | Description | | ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `columns` | `array` | Yes | List of fields to return for each audit event (e.g., 'timestamp', 'source', '@usr.email', '@evt.name'). | | `filter` | `string` | No | Optional Event Platform search string. For example: filter => '@usr.email:user@example.com AND @evt.name:dashboard'. | | `from_timestamp` | `string` | No | Lower time bound for the query; defaults to query context if omitted. | | `to_timestamp` | `string` | No | Upper time bound for the query; defaults to query context if omitted. | ## Example Queries ```sql -- API key usage audit events from the last 24 hours SELECT * FROM dd.audit( columns => ARRAY[ 'timestamp', 'source', '@usr.email', '@evt.name', '@metadata.api_key.id', '@http.method', '@http.url_details.path' ], filter => '@metadata.api_key.id:* AND @evt.name:api_key', from_timestamp => now() - interval '24 hours', to_timestamp => now() ) AS ( ts TIMESTAMP, src VARCHAR, user_email VARCHAR, event_name VARCHAR, api_key_id VARCHAR, http_method VARCHAR, url_path VARCHAR ); ``` ```sql -- Failed authentication attempts by geographic location SELECT * FROM dd.audit( columns => ARRAY[ 'timestamp', '@status', '@auth_method', '@usr.email', '@network.client.geoip.country.name', '@network.client.geoip.city.name', '@network.client.ip' ], filter => '@status:error AND @auth_method:*', from_timestamp => now() - interval '7 days', to_timestamp => now() ) AS ( ts TIMESTAMP, status VARCHAR, auth_method VARCHAR, user_email VARCHAR, country VARCHAR, city VARCHAR, client_ip VARCHAR ); ``` ## Fields | Title | ID | Type | Data Type | Description | | ------------------------- | ------------------------------------------ | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Timestamp | timestamp | core | timestamp | The time when the audit event occurred (e.g., 1771261655440). | | Ingest Size | ingest_size_in_bytes | core | int64 | The size of the audit event payload in bytes at ingestion time (e.g., 1024). | | Source | source | core | string | Source of the audit event indicating the Datadog service or component (e.g., datadog). | | Status | @status | event_attribute | string | Status of the audited action indicating success or failure (e.g., info). | | Authentication Method | @auth_method | event_attribute | string | Method used for authentication during the audited action (e.g., session_cookie). | | Tiebreaker | tiebreaker | core | int64 | Value used to establish deterministic ordering among events with the same timestamp (e.g., 1234567890). | | Event Actor Type | @evt.actor.type | event_attribute | string | Type of actor that performed the audited action (e.g., user). | | HTTP URL Path | @http.url_details.path | event_attribute | string | Path component of the HTTP request URL for API-based audit events (e.g., /api/v1/dashboards). | | Organization UUID | @org.uuid | event_attribute | string | Unique identifier of the organization associated with the audit event (e.g., abc123def-456-789-ghi-jklmnopqrst). | | User UUID | @usr.uuid | event_attribute | string | Unique identifier of the user who performed the audited action (e.g., def456ghi-789-012-jkl-mnopqrstuvwx). | | HTTP URL Host | @http.url_details.host | event_attribute | string | Host component of the HTTP request URL for API-based audit events (e.g., api.datadoghq.com). | | User ID | @usr.id | event_attribute | string | Numeric identifier of the user who performed the audited action (e.g., 1234567). | | Event Name | @evt.name | event_attribute | string | Name or type of the audited event (e.g., dashboard). | | HTTP User Agent | @http.useragent | event_attribute | string | User agent string from the HTTP request header (e.g., Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36). | | Action | @action | event_attribute | string | Specific action that was performed in the audit event (e.g., created). | | Actor | @actor | event_attribute | string | The actor (user or API client) that performed the audited action. | | Asset ID | @asset.id | event_attribute | string | Identifier of the asset or resource involved in the audited action (e.g., abc-123-def). | | App Key ID | @metadata.app_key.id | event_attribute | string | Identifier of the application key used for authentication when auth_method is api_app_keys (e.g., app-key-abc123). | | Personal Access Token ID | @metadata.pat.id | event_attribute | string | Identifier of the Personal Access Token used for authentication when auth_method is pat (e.g., pat-xyz789). | | OAuth Client Name | @metadata.oauth_client.name | event_attribute | string | Name of the OAuth client used for authentication when auth_method is oauth_token (e.g., my-oauth-app). | | Application Key ID | @metadata.application_key.id | event_attribute | string | Identifier of the application key used for API authentication (e.g., app-key-abc123). | | Message | message | core | string | Human-readable message describing the audit event (e.g., User created new dashboard). | | Route Path | @route.path | event_attribute | string | Internal route path for the audited API endpoint (e.g., /api/v1/dashboard/:id). | | Client City | @network.client.geoip.city.name | event_attribute | string | City name derived from the client IP address geolocation (e.g., New York). | | AS Number | @network.client.geoip.as.number | event_attribute | string | Autonomous System number for the client IP address (e.g., 15169). | | AS Name | @network.client.geoip.as.name | event_attribute | string | Autonomous System name for the client IP address (e.g., Google LLC). | | Subdivision ISO Code | @network.client.geoip.subdivision.iso_code | event_attribute | string | ISO code for the subdivision (state/province) from client IP geolocation (e.g., NY). | | AS Route | @network.client.geoip.as.route | event_attribute | string | IP route prefix associated with the client's Autonomous System (e.g., 8.8.8.0/24). | | Subdivision Name | @network.client.geoip.subdivision.name | event_attribute | string | Name of the subdivision (state/province) from client IP geolocation (e.g., New York). | | HTTP Status Code | @http.status_code | event_attribute | string | HTTP response status code for API-based audit events (e.g., 200). | | Continent Name | @network.client.geoip.continent.name | event_attribute | string | Continent name derived from the client IP address geolocation (e.g., North America). | | Event Status | status | core | string | Overall status of the audit event (e.g., info). | | User Email | @usr.email | event_attribute | string | Email address of the user who performed the audited action (e.g., user@example.com). | | Country ISO Code | @network.client.geoip.country.iso_code | event_attribute | string | Two-letter ISO country code from client IP geolocation (e.g., US). | | HTTP Method | @http.method | event_attribute | string | HTTP request method for API-based audit events (e.g., POST). | | API Key ID | @metadata.api_key.id | event_attribute | string | Identifier of the API key used for authentication (e.g., api-key-xyz789). | | Country Name | @network.client.geoip.country.name | event_attribute | string | Country name derived from the client IP address geolocation (e.g., United States). | | Client IP Address | @network.client.ip | event_attribute | string | IP address of the client that initiated the audited action (e.g., 192.168.1.100). | | Geolocated IP Address | @network.client.geoip.ipAddress | event_attribute | string | IP address used for geolocation lookup (e.g., 203.0.113.10). | | Emitted Source | @emitted_source | event_attribute | string | Source component that emitted the audit event (e.g., web-app). | | Timezone | @network.client.geoip.timezone | event_attribute | string | Timezone associated with the client IP address location (e.g., America/New_York). | | Location Latitude | @network.client.geoip.location.latitude | event_attribute | float64 | Latitude coordinate from client IP address geolocation (e.g., 40.7128). | | Organization Name | @org.name | event_attribute | string | Name of the organization associated with the audit event (e.g., Example Corp). | | Asset Type | @asset.type | event_attribute | string | Type of asset or resource involved in the audited action (e.g., dashboard). | | Event UUID | @uuid | event_attribute | string | Unique identifier for the audit event (e.g., 550e8400-e29b-41d4-a716-446655440000). | | Query Data Access Indexes | @asset.new_value.query.data_access.indexes | event_attribute | string | Indexes accessed by queries in the audited asset configuration (e.g., logs-*,metrics-*). | | Query Source | @asset.new_value.query_source | event_attribute | string | Source of the query in the audited asset configuration (e.g., logs). | | Event ID | id | core | string | A unique identifier for the event. | | Discovery Timestamp | discovery_timestamp | core | int64 | The time when Datadog first received the event (milliseconds since Unix epoch). May differ from timestamp if there was an ingestion delay. | | Random Draw | random_draw | core | float64 | A random value between 0.0 and 1.0 assigned at ingestion, useful for consistent sampling across queries. |