autotel-backends 2.12.31 → 2.12.33
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.
- package/package.json +4 -3
- package/skills/autotel-backends/SKILL.md +281 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "autotel-backends",
|
|
3
|
-
"version": "2.12.
|
|
3
|
+
"version": "2.12.33",
|
|
4
4
|
"description": "Vendor backend configurations for Autotel (Honeycomb, Datadog, etc.)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -36,7 +36,8 @@
|
|
|
36
36
|
"files": [
|
|
37
37
|
"dist",
|
|
38
38
|
"src",
|
|
39
|
-
"README.md"
|
|
39
|
+
"README.md",
|
|
40
|
+
"skills"
|
|
40
41
|
],
|
|
41
42
|
"keywords": [
|
|
42
43
|
"opentelemetry",
|
|
@@ -58,7 +59,7 @@
|
|
|
58
59
|
"dependencies": {
|
|
59
60
|
"@opentelemetry/exporter-logs-otlp-http": ">=0.218.0",
|
|
60
61
|
"@opentelemetry/sdk-logs": ">=0.218.0",
|
|
61
|
-
"autotel": "4.
|
|
62
|
+
"autotel": "4.1.0"
|
|
62
63
|
},
|
|
63
64
|
"peerDependencies": {
|
|
64
65
|
"@opentelemetry/exporter-metrics-otlp-http": ">=0.218.0",
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: autotel-backends
|
|
3
|
+
description: >
|
|
4
|
+
Vendor preset configs for autotel that produce a ready-to-use AutotelConfig for Honeycomb, Datadog, Google Cloud, and Grafana Cloud with best-practice defaults already baked in.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# autotel-backends
|
|
8
|
+
|
|
9
|
+
Drop-in configuration presets for popular observability backends. Each preset returns an `AutotelConfig` you pass directly to `autotel`'s `init()`. All vendor-specific concerns (endpoints, auth headers, protocol selection, log processors) are handled for you.
|
|
10
|
+
|
|
11
|
+
Available backends:
|
|
12
|
+
|
|
13
|
+
| Preset | Subpath | Function |
|
|
14
|
+
| ------------- | ------------------------------- | ------------------------- |
|
|
15
|
+
| Honeycomb | `autotel-backends/honeycomb` | `createHoneycombConfig` |
|
|
16
|
+
| Datadog | `autotel-backends/datadog` | `createDatadogConfig` |
|
|
17
|
+
| Google Cloud | `autotel-backends/google-cloud` | `createGoogleCloudConfig` |
|
|
18
|
+
| Grafana Cloud | `autotel-backends/grafana` | `createGrafanaConfig` |
|
|
19
|
+
|
|
20
|
+
## Setup
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add autotel-backends autotel
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
No additional peer dependencies are required for Honeycomb and most Datadog configurations. Google Cloud direct export requires `google-auth-library`. Log export for Datadog and Grafana requires `@opentelemetry/sdk-logs` and `@opentelemetry/exporter-logs-otlp-http` (bundled as direct dependencies).
|
|
27
|
+
|
|
28
|
+
## Configuration / Core Patterns
|
|
29
|
+
|
|
30
|
+
### Honeycomb
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
import { init } from 'autotel';
|
|
34
|
+
import { createHoneycombConfig } from 'autotel-backends/honeycomb';
|
|
35
|
+
|
|
36
|
+
init(
|
|
37
|
+
createHoneycombConfig({
|
|
38
|
+
apiKey: process.env.HONEYCOMB_API_KEY!,
|
|
39
|
+
service: 'my-app',
|
|
40
|
+
}),
|
|
41
|
+
);
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Uses gRPC to `api.honeycomb.io:443`. Sets `x-honeycomb-team` header automatically.
|
|
45
|
+
|
|
46
|
+
**All options:**
|
|
47
|
+
|
|
48
|
+
| Option | Required | Default | Description |
|
|
49
|
+
| ------------- | -------- | ----------------------------- | ------------------------------------------------------------ |
|
|
50
|
+
| `apiKey` | yes | — | Team API key |
|
|
51
|
+
| `service` | yes | — | Service name (= dataset in modern accounts) |
|
|
52
|
+
| `dataset` | no | — | Classic Honeycomb dataset; sets `x-honeycomb-dataset` header |
|
|
53
|
+
| `environment` | no | `NODE_ENV \|\| 'development'` | Deployment environment |
|
|
54
|
+
| `version` | no | auto | Service version |
|
|
55
|
+
| `endpoint` | no | `'api.honeycomb.io:443'` | Override for custom regions or on-prem |
|
|
56
|
+
| `sampleRate` | no | — | Head-based sample rate; sets `x-honeycomb-samplerate` header |
|
|
57
|
+
|
|
58
|
+
### Datadog
|
|
59
|
+
|
|
60
|
+
Two modes: **direct cloud ingestion** (API key required) and **local Datadog Agent** (no key needed).
|
|
61
|
+
|
|
62
|
+
**Direct cloud ingestion:**
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
import { init } from 'autotel';
|
|
66
|
+
import { createDatadogConfig } from 'autotel-backends/datadog';
|
|
67
|
+
|
|
68
|
+
init(
|
|
69
|
+
createDatadogConfig({
|
|
70
|
+
apiKey: process.env.DATADOG_API_KEY!,
|
|
71
|
+
service: 'my-app',
|
|
72
|
+
environment: 'production',
|
|
73
|
+
enableLogs: true,
|
|
74
|
+
}),
|
|
75
|
+
);
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Local Datadog Agent (Kubernetes / long-running services):**
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
init(
|
|
82
|
+
createDatadogConfig({
|
|
83
|
+
service: 'my-api',
|
|
84
|
+
useAgent: true,
|
|
85
|
+
agentHost: 'datadog-agent.default.svc.cluster.local',
|
|
86
|
+
}),
|
|
87
|
+
);
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**All options:**
|
|
91
|
+
|
|
92
|
+
| Option | Required | Default | Description |
|
|
93
|
+
| --------------------- | -------------- | ---------------------- | ------------------------------------------------------------------------- |
|
|
94
|
+
| `apiKey` | if `!useAgent` | — | Datadog API key |
|
|
95
|
+
| `service` | yes | — | Service name |
|
|
96
|
+
| `site` | no | `'datadoghq.com'` | Datadog site region (`datadoghq.eu`, `us3.datadoghq.com`, etc.) |
|
|
97
|
+
| `environment` | no | `DD_ENV \|\| NODE_ENV` | Deployment environment |
|
|
98
|
+
| `version` | no | `DD_VERSION \|\| auto` | Service version |
|
|
99
|
+
| `enableLogs` | no | `false` | Export OTel logs via OTLP; also sets `OTEL_EXPORTER_OTLP_LOGS_*` env vars |
|
|
100
|
+
| `useAgent` | no | `false` | Route telemetry to local Datadog Agent instead of direct cloud ingestion |
|
|
101
|
+
| `agentHost` | no | `'localhost'` | Agent hostname (when `useAgent: true`) |
|
|
102
|
+
| `agentPort` | no | `4318` | Agent OTLP HTTP port (when `useAgent: true`) |
|
|
103
|
+
| `logRecordProcessors` | no | — | Override default log processor (advanced) |
|
|
104
|
+
|
|
105
|
+
When `enableLogs: true`, the preset auto-sets `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`, and `OTEL_EXPORTER_OTLP_LOGS_HEADERS` environment variables (only if not already set), enabling `pino-opentelemetry-transport` without extra configuration.
|
|
106
|
+
|
|
107
|
+
### Google Cloud
|
|
108
|
+
|
|
109
|
+
**Via OpenTelemetry Collector (recommended — no auth in app):**
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import { init } from 'autotel';
|
|
113
|
+
import { createGoogleCloudConfig } from 'autotel-backends/google-cloud';
|
|
114
|
+
|
|
115
|
+
init(
|
|
116
|
+
createGoogleCloudConfig({
|
|
117
|
+
projectId: process.env.GOOGLE_CLOUD_PROJECT!,
|
|
118
|
+
service: 'my-app',
|
|
119
|
+
useCollector: true,
|
|
120
|
+
collectorEndpoint: 'http://localhost:4318',
|
|
121
|
+
}),
|
|
122
|
+
);
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**Direct export (requires `google-auth-library`):**
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pnpm add google-auth-library
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```typescript
|
|
132
|
+
init(
|
|
133
|
+
createGoogleCloudConfig({
|
|
134
|
+
projectId: process.env.GOOGLE_CLOUD_PROJECT!,
|
|
135
|
+
service: 'my-app',
|
|
136
|
+
}),
|
|
137
|
+
);
|
|
138
|
+
// Uses Application Default Credentials (ADC) automatically
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**All options:**
|
|
142
|
+
|
|
143
|
+
| Option | Required | Default | Description |
|
|
144
|
+
| ------------------- | -------- | ------------------------------------ | --------------------------------------------------- |
|
|
145
|
+
| `projectId` | yes | — | GCP project ID (also from `GOOGLE_CLOUD_PROJECT`) |
|
|
146
|
+
| `service` | yes | — | Service name |
|
|
147
|
+
| `environment` | no | `NODE_ENV` | Deployment environment |
|
|
148
|
+
| `version` | no | `GCP_VERSION \|\| VERSION` | Service version |
|
|
149
|
+
| `useCollector` | no | `false` | Send to local Collector; Collector handles GCP auth |
|
|
150
|
+
| `collectorEndpoint` | no | `'http://localhost:4318'` | OTLP Collector address |
|
|
151
|
+
| `endpoint` | no | `'https://telemetry.googleapis.com'` | Override Telemetry API base URL |
|
|
152
|
+
|
|
153
|
+
### Grafana Cloud
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
import { init } from 'autotel';
|
|
157
|
+
import { createGrafanaConfig } from 'autotel-backends/grafana';
|
|
158
|
+
|
|
159
|
+
init(
|
|
160
|
+
createGrafanaConfig({
|
|
161
|
+
endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
|
|
162
|
+
headers: process.env.OTEL_EXPORTER_OTLP_HEADERS,
|
|
163
|
+
service: 'my-app',
|
|
164
|
+
enableLogs: true,
|
|
165
|
+
}),
|
|
166
|
+
);
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Get `endpoint` and `headers` from: Grafana Cloud portal → your stack → Connections → OpenTelemetry → Configure.
|
|
170
|
+
|
|
171
|
+
**All options:**
|
|
172
|
+
|
|
173
|
+
| Option | Required | Default | Description |
|
|
174
|
+
| --------------------- | -------- | ---------------------- | ------------------------------------------------------------------- |
|
|
175
|
+
| `endpoint` | yes | — | OTLP gateway endpoint |
|
|
176
|
+
| `headers` | no | — | Auth headers; accepts `"Key=Value,Key2=Value2"` string or an object |
|
|
177
|
+
| `service` | yes | — | Service name |
|
|
178
|
+
| `environment` | no | `NODE_ENV` | Deployment environment |
|
|
179
|
+
| `version` | no | `OTEL_SERVICE_VERSION` | Service version |
|
|
180
|
+
| `enableLogs` | no | `true` | Export logs to Grafana Loki via OTLP |
|
|
181
|
+
| `logRecordProcessors` | no | — | Override default log processor (advanced) |
|
|
182
|
+
|
|
183
|
+
Grafana preset also enables `metrics: true` by default. Logs go to `/v1/logs` on the same gateway.
|
|
184
|
+
|
|
185
|
+
## Common Mistakes
|
|
186
|
+
|
|
187
|
+
### HIGH — Passing apiKey to Datadog with useAgent: true
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
// WRONG: apiKey is ignored and Agent mode doesn't use it
|
|
191
|
+
init(
|
|
192
|
+
createDatadogConfig({
|
|
193
|
+
apiKey: process.env.DATADOG_API_KEY!,
|
|
194
|
+
service: 'my-api',
|
|
195
|
+
useAgent: true,
|
|
196
|
+
}),
|
|
197
|
+
);
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
// CORRECT: omit apiKey when using Agent — Agent handles authentication
|
|
202
|
+
init(
|
|
203
|
+
createDatadogConfig({
|
|
204
|
+
service: 'my-api',
|
|
205
|
+
useAgent: true,
|
|
206
|
+
}),
|
|
207
|
+
);
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### HIGH — Calling init() without apiKey in direct Datadog mode
|
|
211
|
+
|
|
212
|
+
`createDatadogConfig` throws at call-time if `!useAgent && !apiKey`. This is a startup crash, not a runtime one.
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
// WRONG: missing apiKey
|
|
216
|
+
init(createDatadogConfig({ service: 'my-app' }));
|
|
217
|
+
// throws: "Datadog API key is required..."
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### HIGH — Trying Google Cloud direct export without google-auth-library installed
|
|
221
|
+
|
|
222
|
+
```typescript
|
|
223
|
+
// WRONG: throws at runtime if package is absent
|
|
224
|
+
init(createGoogleCloudConfig({ projectId: 'my-project', service: 'my-app' }));
|
|
225
|
+
// throws: "Direct export to Google Cloud requires google-auth-library..."
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
```typescript
|
|
229
|
+
// CORRECT: either install the package or use useCollector: true
|
|
230
|
+
pnpm add google-auth-library
|
|
231
|
+
// or:
|
|
232
|
+
init(createGoogleCloudConfig({
|
|
233
|
+
projectId: 'my-project',
|
|
234
|
+
service: 'my-app',
|
|
235
|
+
useCollector: true,
|
|
236
|
+
}));
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### MEDIUM — Using wrong Honeycomb API key type
|
|
240
|
+
|
|
241
|
+
Modern Honeycomb environments use a team-level API key. Classic environments use dataset-specific keys. If traces are missing, verify key type in Honeycomb's account settings. The `dataset` option is only needed for classic accounts.
|
|
242
|
+
|
|
243
|
+
### MEDIUM — Setting OTEL*EXPORTER_OTLP_LOGS*\* env vars before calling createDatadogConfig with enableLogs
|
|
244
|
+
|
|
245
|
+
The Datadog preset respects existing env vars and skips overwriting them. If you set `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` manually to the wrong value before calling the preset, the preset's correct value is silently skipped.
|
|
246
|
+
|
|
247
|
+
```typescript
|
|
248
|
+
// RISKY: if this env var is already set incorrectly, the preset won't fix it
|
|
249
|
+
process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT = 'http://wrong-host';
|
|
250
|
+
init(createDatadogConfig({ apiKey: key, service: 'app', enableLogs: true }));
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Clear or unset conflicting env vars before calling the preset, or pass `logRecordProcessors` directly.
|
|
254
|
+
|
|
255
|
+
### MEDIUM — Stripping the /v1/traces suffix from Grafana endpoint
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
// WRONG: Grafana gateway expects the full base URL; the SDK appends /v1/traces
|
|
259
|
+
init(
|
|
260
|
+
createGrafanaConfig({
|
|
261
|
+
endpoint: 'https://otlp-gateway-prod-gb-south-1.grafana.net/otlp/v1/traces',
|
|
262
|
+
// ...
|
|
263
|
+
}),
|
|
264
|
+
);
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
// CORRECT: base endpoint without signal path
|
|
269
|
+
init(
|
|
270
|
+
createGrafanaConfig({
|
|
271
|
+
endpoint: 'https://otlp-gateway-prod-gb-south-1.grafana.net/otlp',
|
|
272
|
+
// ...
|
|
273
|
+
}),
|
|
274
|
+
);
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The preset automatically derives `/v1/logs` for log export by stripping any trailing signal path.
|
|
278
|
+
|
|
279
|
+
## Version
|
|
280
|
+
|
|
281
|
+
Targets autotel-backends v2.12.4. Direct deps: `@opentelemetry/exporter-logs-otlp-http` >=0.213.0, `@opentelemetry/sdk-logs` >=0.213.0. Optional peers: `google-auth-library` >=10.6.2 (Google Cloud direct export only). See also: `autotel` (core `init()`), `autotel-adapters` (HTTP framework adapters), `autotel-aws` (AWS instrumentation).
|