> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Datadog Integration

> Forward Grantex authorization events to Datadog for centralized logging, dashboards, and anomaly detection monitors.

The `@grantex/destinations` package includes a `DatadogDestination` that sends Grantex events to the Datadog Logs API. This guide covers setup, configuration, and example monitors for production alerting.

## Prerequisites

* A Datadog account with a **Logs API key** (not an application key)
* The `@grantex/destinations` package installed:

```bash theme={null}
npm install @grantex/destinations
```

## Setup

```typescript theme={null}
import { EventSource, DatadogDestination } from '@grantex/destinations';

const source = new EventSource({
  url: 'https://api.grantex.dev',
  apiKey: process.env.GRANTEX_API_KEY!,
});

const datadog = new DatadogDestination({
  apiKey: process.env.DD_API_KEY!,
  site: 'datadoghq.com',       // or datadoghq.eu, us5.datadoghq.com, etc.
  service: 'grantex',
  source: 'grantex',
  batchSize: 100,
  flushIntervalMs: 5000,
});

source.addDestination(datadog);
await source.start();
```

## Configuration Options

| Option | Type | Default | Description |
| - | - | - | - |
| `apiKey` | `string` | **required** | Datadog API key for the Logs API |
| `site` | `string` | `datadoghq.com` | Datadog site (e.g., `datadoghq.eu`, `us5.datadoghq.com`) |
| `service` | `string` | `grantex` | Service name tag applied to all logs |
| `source` | `string` | `grantex` | Source tag (`ddsource`) applied to all logs |
| `batchSize` | `number` | `100` | Number of events to buffer before flushing to Datadog |
| `flushIntervalMs` | `number` | — | Flush buffered events on a timer (milliseconds) |

## How It Works

The `DatadogDestination` buffers incoming events and flushes them in batches to the [Datadog Logs HTTP API](https://docs.datadoghq.com/api/latest/logs/#send-logs) (`POST https://http-intake.logs.<site>/api/v2/logs`).

Each Grantex event becomes a Datadog log entry with:

| Field | Value |
| - | - |
| `ddsource` | Value of `source` config (default: `grantex`) |
| `ddtags` | `type:<event-type>` (e.g., `type:grant.created`) |
| `hostname` | `grantex-auth-service` |
| `service` | Value of `service` config (default: `grantex`) |
| `message` | Full JSON-serialized Grantex event |

## Filtering Event Types

To send only specific events to Datadog, filter at the `EventSource` level:

```typescript theme={null}
const source = new EventSource({
  url: 'https://api.grantex.dev',
  apiKey: process.env.GRANTEX_API_KEY!,
  types: ['grant.created', 'grant.revoked', 'budget.exhausted'],
});
```

## Datadog Log Pipeline

Create a [Datadog log pipeline](https://docs.datadoghq.com/logs/log_configuration/pipelines/) to parse Grantex events:

1. Go to **Logs > Configuration > Pipelines**
2. Create a new pipeline with filter `source:grantex`
3. Add a **JSON Mapper** processor to extract fields from `message`:
   * `event.type` -> `grantex.event_type`
   * `event.data.grantId` -> `grantex.grant_id`
   * `event.data.agentId` -> `grantex.agent_id`
   * `event.data.principalId` -> `grantex.principal_id`
   * `event.data.scopes` -> `grantex.scopes`
4. Add a **Category Processor** on `grantex.event_type` to set severity:
   * `grant.revoked` -> `warn`
   * `budget.exhausted` -> `error`
   * Everything else -> `info`

## Example Monitors

### High Grant Revocation Rate

Alert when grant revocations exceed a threshold, which may indicate a security incident or misconfigured agent.

```
Monitor type: Log Count
Query: source:grantex type:grant.revoked
Threshold:
  Warning:  > 10 in 5 minutes
  Critical: > 50 in 5 minutes
Message:
  High grant revocation rate detected.
  {{#is_alert}}More than 50 grants revoked in 5 minutes — possible security incident.{{/is_alert}}
  {{#is_warning}}More than 10 grants revoked in 5 minutes — investigate agent behavior.{{/is_warning}}
```

### Budget Exhaustion

Alert immediately when any budget is fully consumed.

```
Monitor type: Log Count
Query: source:grantex type:budget.exhausted
Threshold:
  Critical: > 0 in 1 minute
Message:
  A Grantex budget has been exhausted.
  Review the event details in the log explorer to identify the affected grant and agent.
```

### No Events Received (Heartbeat)

Detect if the event stream connection drops.

```
Monitor type: Log Count
Query: source:grantex
Threshold:
  Critical: < 1 in 15 minutes
Message:
  No Grantex events received in the last 15 minutes.
  Check the @grantex/destinations process and network connectivity.
```

### Anomalous Token Issuance

Detect spikes in token issuance that deviate from the baseline.

```
Monitor type: Anomaly Detection
Query: count:source:grantex type:token.issued
Algorithm: agile
Deviation: 3
Message:
  Anomalous spike in Grantex token issuance detected.
  This may indicate a compromised API key or runaway agent.
```

## Datadog Dashboard

Create a dashboard with these widgets for a Grantex overview:

| Widget | Query | Visualization |
| - | - | - |
| Events by type | `source:grantex` group by `@grantex.event_type` | Timeseries (stacked bars) |
| Grants created | `source:grantex type:grant.created` | Query Value |
| Grants revoked | `source:grantex type:grant.revoked` | Query Value |
| Budget alerts | `source:grantex type:budget.*` | Event Stream |
| Top agents | `source:grantex` group by `@grantex.agent_id` | Top List |

## Graceful Shutdown

Ensure buffered events are flushed before your process exits:

```typescript theme={null}
process.on('SIGTERM', async () => {
  await source.stop();  // flushes all destinations and closes connections
  process.exit(0);
});
```

## Next Steps

* [Event Streaming](/guides/event-streaming) — SSE/WebSocket architecture overview
* [Splunk Integration](/guides/siem-splunk) — forward events to Splunk HEC
* [S3 & BigQuery Archival](/guides/siem-s3-bigquery) — long-term compliance storage
* [Metrics & Observability](/guides/metrics-observability) — Prometheus metrics and Grafana dashboards

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.