@rawdash/connector-datadog 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +114 -0
  2. package/dist/index.d.ts +314 -0
  3. package/dist/index.js +841 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +42 -0
package/README.md ADDED
@@ -0,0 +1,114 @@
1
+ <!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
2
+
3
+ # @rawdash/connector-datadog
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@rawdash/connector-datadog)](https://www.npmjs.com/package/@rawdash/connector-datadog)
6
+ [![license](https://img.shields.io/npm/l/@rawdash/connector-datadog)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
7
+
8
+ Sync monitor health, monitor state-change events, incidents, SLOs, and user-declared metric queries from a Datadog org.
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ npm install @rawdash/connector-datadog
14
+ ```
15
+
16
+ ## Authentication
17
+
18
+ A Datadog API key and Application key are required, scoped to the org and site you want to read from. Both are stored as secrets.
19
+
20
+ 1. Open Datadog → Organization Settings → API Keys and create (or copy) an API key.
21
+ 2. Open Datadog → Organization Settings → Application Keys and create an Application key with read access to monitors, incidents, SLOs, and metrics.
22
+ 3. Store both as secrets and reference them from the connector config as `apiKey: secret("DD_API_KEY")` and `appKey: secret("DD_APP_KEY")`.
23
+ 4. Set `site` to your Datadog site host (e.g. `datadoghq.com`, `datadoghq.eu`, `us3.datadoghq.com`); it defaults to `datadoghq.com`.
24
+
25
+ ## Configuration
26
+
27
+ | Field | Type | Required | Description |
28
+ | ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
29
+ | `apiKey` | secret | Yes | Datadog API key. Create at Datadog → Organization Settings → API Keys. |
30
+ | `appKey` | secret | Yes | Datadog Application key. Create at Datadog → Organization Settings → Application Keys. Used in tandem with the API key to authenticate REST calls. |
31
+ | `site` | string | No | Datadog site host (e.g. `datadoghq.com`, `datadoghq.eu`, `us3.datadoghq.com`). Defaults to `datadoghq.com`. |
32
+ | `metricQueries` | array | No | User-declared metric timeseries queries. Each entry produces `datadog_metric` samples named `<name>` from the Datadog Metrics Query API. |
33
+ | `resources` | array | No | Which Datadog resources to sync. Omit to sync all of them. 'monitor_events' depends on 'monitors' being fetched - enabling it without 'monitors' still runs the monitors query but skips writing monitor entities. |
34
+ | `metricsLookbackHours` | number | No | Window of metric samples to pull on each sync, in hours. Defaults to 24. |
35
+
36
+ ## Resources
37
+
38
+ - **`datadog_monitor`** _(entity)_ - Datadog monitors with name, type, current status (OK / Alert / Warn / No Data), priority, and tags.
39
+ - Endpoint: `GET /api/v1/monitor/search`
40
+ - **`datadog_monitor_event`** _(event)_ - Monitor state-transition events, emitted whenever a monitor's status changes from its previously-stored value.
41
+ - Derived by diffing each monitor's current status against the last-synced status, so it depends on the monitors phase running and on prior monitor state being stored.
42
+ - **`datadog_incident`** _(entity)_ - Datadog incidents with title, severity, state, and created / resolved timestamps.
43
+ - Endpoint: `GET /api/v2/incidents`
44
+ - **`datadog_slo`** _(entity)_ - Service Level Objectives with type, thresholds, primary target, and latest SLI value.
45
+ - Endpoint: `GET /api/v1/slo`
46
+ - **`datadog_slo_sli`** _(metric)_ - SLI value samples per SLO, one per overall_status snapshot reported by Datadog.
47
+ - Unit: percent
48
+ - Dimensions: `sloId`, `sloType`
49
+ - **`datadog_metric`** _(metric)_ - User-declared metric timeseries samples, stored as `datadog_metric.<query name>`, from the Datadog Metrics Query API.
50
+ - Endpoint: `POST /api/v2/query/timeseries`
51
+ - Dimensions: `queryName`, `query`, `tags`
52
+
53
+ ## Example
54
+
55
+ ```ts
56
+ import {
57
+ defineConfig,
58
+ defineDashboard,
59
+ defineMetric,
60
+ secret,
61
+ } from '@rawdash/core';
62
+
63
+ const datadog = {
64
+ name: 'datadog',
65
+ connectorId: 'datadog',
66
+ config: {
67
+ apiKey: secret('DD_API_KEY'),
68
+ appKey: secret('DD_APP_KEY'),
69
+ site: 'datadoghq.com',
70
+ },
71
+ };
72
+
73
+ export default defineConfig({
74
+ connectors: [datadog],
75
+ dashboards: {
76
+ observability: defineDashboard({
77
+ widgets: {
78
+ monitors_in_alert: {
79
+ kind: 'stat',
80
+ title: 'Monitors in Alert',
81
+ metric: defineMetric({
82
+ connector: datadog,
83
+ shape: 'entity',
84
+ entityType: 'datadog_monitor',
85
+ fn: 'count',
86
+ filter: [{ field: 'status', op: 'eq', value: 'Alert' }],
87
+ }),
88
+ },
89
+ },
90
+ }),
91
+ },
92
+ });
93
+ ```
94
+
95
+ ## Rate limits
96
+
97
+ Datadog returns X-RateLimit-Remaining / X-RateLimit-Reset headers (reset in seconds) on the v2 endpoints, wired through the standard rate-limit policy so the host scheduler backs off on near-empty windows.
98
+
99
+ ## Limitations
100
+
101
+ - Logs and RUM session data are out of scope (high volume, low dashboard signal).
102
+ - Synthetic monitor results are out of scope.
103
+ - Monitor entities are not cleared on a full sync - the monitor_events diff depends on the prior status being stored.
104
+ - Pagination URLs are pinned to the configured `api.<site>` host.
105
+
106
+ ## Links
107
+
108
+ - [Rawdash docs](https://rawdash.dev/docs/connectors/)
109
+ - [Datadog API docs](https://docs.datadoghq.com/api/latest/)
110
+ - [GitHub](https://github.com/rawdash/rawdash)
111
+
112
+ ## License
113
+
114
+ Apache-2.0
package/dist/index.d.ts ADDED
@@ -0,0 +1,314 @@
1
+ import { BaseConnector, ConnectorContext, SyncOptions, StorageHandle, SyncResult, ConnectorDoc } from '@rawdash/core';
2
+ import { z } from 'zod';
3
+
4
+ declare const configFields: z.ZodObject<{
5
+ apiKey: z.ZodObject<{
6
+ $secret: z.ZodString;
7
+ }, z.core.$strip>;
8
+ appKey: z.ZodObject<{
9
+ $secret: z.ZodString;
10
+ }, z.core.$strip>;
11
+ site: z.ZodOptional<z.ZodString>;
12
+ metricQueries: z.ZodOptional<z.ZodArray<z.ZodObject<{
13
+ name: z.ZodString;
14
+ query: z.ZodString;
15
+ interval: z.ZodOptional<z.ZodEnum<{
16
+ "5m": "5m";
17
+ "15m": "15m";
18
+ "1h": "1h";
19
+ "1d": "1d";
20
+ }>>;
21
+ }, z.core.$strip>>>;
22
+ resources: z.ZodOptional<z.ZodArray<z.ZodEnum<{
23
+ monitors: "monitors";
24
+ monitor_events: "monitor_events";
25
+ incidents: "incidents";
26
+ slos: "slos";
27
+ metric_queries: "metric_queries";
28
+ }>>>;
29
+ metricsLookbackHours: z.ZodOptional<z.ZodNumber>;
30
+ }, z.core.$strip>;
31
+ declare const doc: ConnectorDoc;
32
+ type DatadogResource = 'monitors' | 'monitor_events' | 'incidents' | 'slos' | 'metric_queries';
33
+ interface DatadogMetricQuery {
34
+ name: string;
35
+ query: string;
36
+ interval?: '5m' | '15m' | '1h' | '1d';
37
+ }
38
+ interface DatadogSettings {
39
+ site?: string;
40
+ metricQueries?: readonly DatadogMetricQuery[];
41
+ resources?: readonly DatadogResource[];
42
+ metricsLookbackHours?: number;
43
+ }
44
+ declare const datadogCredentials: {
45
+ apiKey: {
46
+ description: string;
47
+ auth: "required";
48
+ };
49
+ appKey: {
50
+ description: string;
51
+ auth: "required";
52
+ };
53
+ };
54
+ type DatadogCredentials = typeof datadogCredentials;
55
+ declare class DatadogConnector extends BaseConnector<DatadogSettings, DatadogCredentials> {
56
+ static readonly id = "datadog";
57
+ static readonly resources: {
58
+ readonly datadog_monitor: {
59
+ readonly shape: "entity";
60
+ readonly description: "Datadog monitors with name, type, current status (OK / Alert / Warn / No Data), priority, and tags.";
61
+ readonly endpoint: "GET /api/v1/monitor/search";
62
+ readonly responses: {
63
+ readonly monitors: z.ZodObject<{
64
+ monitors: z.ZodArray<z.ZodObject<{
65
+ id: z.ZodNumber;
66
+ name: z.ZodString;
67
+ type: z.ZodString;
68
+ status: z.ZodEnum<{
69
+ OK: "OK";
70
+ Alert: "Alert";
71
+ Warn: "Warn";
72
+ "No Data": "No Data";
73
+ Ignored: "Ignored";
74
+ }>;
75
+ priority: z.ZodNullable<z.ZodNumber>;
76
+ tags: z.ZodArray<z.ZodString>;
77
+ overall_state_modified: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
78
+ created: z.ZodISODateTime;
79
+ modified: z.ZodISODateTime;
80
+ }, z.core.$strip>>;
81
+ metadata: z.ZodObject<{
82
+ page: z.ZodNumber;
83
+ page_count: z.ZodNumber;
84
+ per_page: z.ZodNumber;
85
+ total_count: z.ZodNumber;
86
+ }, z.core.$strip>;
87
+ }, z.core.$strip>;
88
+ };
89
+ };
90
+ readonly datadog_monitor_event: {
91
+ readonly shape: "event";
92
+ readonly description: "Monitor state-transition events, emitted whenever a monitor's status changes from its previously-stored value.";
93
+ readonly notes: "Derived by diffing each monitor's current status against the last-synced status, so it depends on the monitors phase running and on prior monitor state being stored.";
94
+ };
95
+ readonly datadog_incident: {
96
+ readonly shape: "entity";
97
+ readonly description: "Datadog incidents with title, severity, state, and created / resolved timestamps.";
98
+ readonly endpoint: "GET /api/v2/incidents";
99
+ readonly responses: {
100
+ readonly incidents: z.ZodObject<{
101
+ data: z.ZodArray<z.ZodObject<{
102
+ id: z.ZodString;
103
+ type: z.ZodLiteral<"incidents">;
104
+ attributes: z.ZodObject<{
105
+ title: z.ZodString;
106
+ severity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
107
+ state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
108
+ customer_impact_scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
109
+ created: z.ZodISODateTime;
110
+ modified: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
111
+ resolved: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
112
+ }, z.core.$strip>;
113
+ }, z.core.$strip>>;
114
+ meta: z.ZodOptional<z.ZodObject<{
115
+ pagination: z.ZodOptional<z.ZodObject<{
116
+ next_offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
117
+ offset: z.ZodOptional<z.ZodNumber>;
118
+ size: z.ZodOptional<z.ZodNumber>;
119
+ }, z.core.$strip>>;
120
+ }, z.core.$strip>>;
121
+ }, z.core.$strip>;
122
+ };
123
+ };
124
+ readonly datadog_slo: {
125
+ readonly shape: "entity";
126
+ readonly description: "Service Level Objectives with type, thresholds, primary target, and latest SLI value.";
127
+ readonly endpoint: "GET /api/v1/slo";
128
+ readonly responses: {
129
+ readonly slos: z.ZodObject<{
130
+ data: z.ZodArray<z.ZodObject<{
131
+ id: z.ZodString;
132
+ name: z.ZodString;
133
+ type: z.ZodString;
134
+ thresholds: z.ZodArray<z.ZodObject<{
135
+ timeframe: z.ZodString;
136
+ target: z.ZodNumber;
137
+ warning: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
138
+ }, z.core.$strip>>;
139
+ overall_status: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
140
+ sli_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
141
+ indexed_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
142
+ }, z.core.$strip>>>>;
143
+ created_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
144
+ modified_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
145
+ }, z.core.$strip>>;
146
+ }, z.core.$strip>;
147
+ };
148
+ };
149
+ readonly datadog_slo_sli: {
150
+ readonly shape: "metric";
151
+ readonly description: "SLI value samples per SLO, one per overall_status snapshot reported by Datadog.";
152
+ readonly unit: "percent";
153
+ readonly dimensions: [{
154
+ readonly name: "sloId";
155
+ readonly description: "Datadog SLO id.";
156
+ }, {
157
+ readonly name: "sloType";
158
+ readonly description: "SLO type (metric, monitor, etc.).";
159
+ }];
160
+ };
161
+ readonly datadog_metric: {
162
+ readonly shape: "metric";
163
+ readonly dynamic: true;
164
+ readonly description: "User-declared metric timeseries samples, stored as `datadog_metric.<query name>`, from the Datadog Metrics Query API.";
165
+ readonly endpoint: "POST /api/v2/query/timeseries";
166
+ readonly dimensions: [{
167
+ readonly name: "queryName";
168
+ readonly description: "The user-declared query name.";
169
+ }, {
170
+ readonly name: "query";
171
+ readonly description: "The Datadog metrics query string.";
172
+ }, {
173
+ readonly name: "tags";
174
+ readonly description: "Comma-joined group tags for the series, or `*` when the series is ungrouped.";
175
+ }];
176
+ readonly responses: {
177
+ readonly metric_queries: z.ZodObject<{
178
+ data: z.ZodObject<{
179
+ type: z.ZodLiteral<"timeseries_response">;
180
+ attributes: z.ZodObject<{
181
+ series: z.ZodOptional<z.ZodArray<z.ZodObject<{
182
+ group_tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
183
+ query_index: z.ZodOptional<z.ZodNumber>;
184
+ }, z.core.$strip>>>;
185
+ times: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
186
+ values: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
187
+ }, z.core.$strip>;
188
+ }, z.core.$strip>;
189
+ }, z.core.$strip>;
190
+ };
191
+ };
192
+ };
193
+ static readonly schemas: object & {
194
+ readonly monitors: z.ZodObject<{
195
+ monitors: z.ZodArray<z.ZodObject<{
196
+ id: z.ZodNumber;
197
+ name: z.ZodString;
198
+ type: z.ZodString;
199
+ status: z.ZodEnum<{
200
+ OK: "OK";
201
+ Alert: "Alert";
202
+ Warn: "Warn";
203
+ "No Data": "No Data";
204
+ Ignored: "Ignored";
205
+ }>;
206
+ priority: z.ZodNullable<z.ZodNumber>;
207
+ tags: z.ZodArray<z.ZodString>;
208
+ overall_state_modified: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
209
+ created: z.ZodISODateTime;
210
+ modified: z.ZodISODateTime;
211
+ }, z.core.$strip>>;
212
+ metadata: z.ZodObject<{
213
+ page: z.ZodNumber;
214
+ page_count: z.ZodNumber;
215
+ per_page: z.ZodNumber;
216
+ total_count: z.ZodNumber;
217
+ }, z.core.$strip>;
218
+ }, z.core.$strip>;
219
+ } & {
220
+ readonly incidents: z.ZodObject<{
221
+ data: z.ZodArray<z.ZodObject<{
222
+ id: z.ZodString;
223
+ type: z.ZodLiteral<"incidents">;
224
+ attributes: z.ZodObject<{
225
+ title: z.ZodString;
226
+ severity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
227
+ state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
228
+ customer_impact_scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
229
+ created: z.ZodISODateTime;
230
+ modified: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
231
+ resolved: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
232
+ }, z.core.$strip>;
233
+ }, z.core.$strip>>;
234
+ meta: z.ZodOptional<z.ZodObject<{
235
+ pagination: z.ZodOptional<z.ZodObject<{
236
+ next_offset: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
237
+ offset: z.ZodOptional<z.ZodNumber>;
238
+ size: z.ZodOptional<z.ZodNumber>;
239
+ }, z.core.$strip>>;
240
+ }, z.core.$strip>>;
241
+ }, z.core.$strip>;
242
+ } & {
243
+ readonly slos: z.ZodObject<{
244
+ data: z.ZodArray<z.ZodObject<{
245
+ id: z.ZodString;
246
+ name: z.ZodString;
247
+ type: z.ZodString;
248
+ thresholds: z.ZodArray<z.ZodObject<{
249
+ timeframe: z.ZodString;
250
+ target: z.ZodNumber;
251
+ warning: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
252
+ }, z.core.$strip>>;
253
+ overall_status: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
254
+ sli_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
255
+ indexed_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
256
+ }, z.core.$strip>>>>;
257
+ created_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
258
+ modified_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
259
+ }, z.core.$strip>>;
260
+ }, z.core.$strip>;
261
+ } & {
262
+ readonly metric_queries: z.ZodObject<{
263
+ data: z.ZodObject<{
264
+ type: z.ZodLiteral<"timeseries_response">;
265
+ attributes: z.ZodObject<{
266
+ series: z.ZodOptional<z.ZodArray<z.ZodObject<{
267
+ group_tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
268
+ query_index: z.ZodOptional<z.ZodNumber>;
269
+ }, z.core.$strip>>>;
270
+ times: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
271
+ values: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
272
+ }, z.core.$strip>;
273
+ }, z.core.$strip>;
274
+ }, z.core.$strip>;
275
+ } & Readonly<Record<string, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
276
+ static create(input: unknown, ctx?: ConnectorContext): DatadogConnector;
277
+ readonly id = "datadog";
278
+ readonly credentials: {
279
+ apiKey: {
280
+ description: string;
281
+ auth: "required";
282
+ };
283
+ appKey: {
284
+ description: string;
285
+ auth: "required";
286
+ };
287
+ };
288
+ private get apiHost();
289
+ private get apiBase();
290
+ private buildHeaders;
291
+ private fetch;
292
+ private postJson;
293
+ private activePhases;
294
+ private allowedPagePath;
295
+ private sanitizePageUrl;
296
+ private resolveCursor;
297
+ private buildInitialMonitorsUrl;
298
+ private buildNextMonitorsUrl;
299
+ private buildInitialIncidentsUrl;
300
+ private buildNextIncidentsUrl;
301
+ private buildSlosUrl;
302
+ private buildMetricsUrl;
303
+ private fetchMonitorsPage;
304
+ private fetchIncidentsPage;
305
+ private fetchSlos;
306
+ private fetchMetrics;
307
+ private writeMonitorsBatch;
308
+ private writeIncidents;
309
+ private writeSlos;
310
+ private writeMetrics;
311
+ sync(options: SyncOptions, storage: StorageHandle, signal?: AbortSignal): Promise<SyncResult>;
312
+ }
313
+
314
+ export { DatadogConnector, type DatadogResource, type DatadogSettings, configFields, DatadogConnector as default, doc };