@deliciousmonster/datadog-agent-binary 7.82.1-next.1 → 7.82.1-next.2

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 (2) hide show
  1. package/README.md +23 -98
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,36 +1,26 @@
1
1
  # @deliciousmonster/datadog-agent-binary
2
2
 
3
- [![Datadog Agent Binaries](https://github.com/deliciousmonster/datadog-agent-binary/actions/workflows/build-release.yml/badge.svg)](https://github.com/deliciousmonster/datadog-agent-binary/actions/workflows/build-release.yml)
3
+ [![Test](https://github.com/deliciousmonster/datadog-agent-binary/actions/workflows/test.yml/badge.svg)](https://github.com/deliciousmonster/datadog-agent-binary/actions/workflows/test.yml)
4
4
 
5
- A Harper v5 plugin that runs the Datadog core agent and trace-agent alongside a node, so host metrics and the spans the host application's own `dd-trace` produces reach Datadog. `dd-trace` itself is the application's, not shipped here. Both agents arrive as pre-compiled binaries, one npm package per platform, picked by `optionalDependencies`; nothing is downloaded at install time and no install script runs.
5
+ A Harper v5 plugin that runs the Datadog core agent and trace-agent beside a node, so host metrics and the spans your application's `dd-trace` produces reach Datadog. The agents ship as prebuilt binaries, one npm package per platform; npm installs the one matching the host, and no install script runs.
6
6
 
7
- The binaries are how the plugin does its job, not a product of their own. Running them outside a Harper node is not a surface this package supports.
7
+ ## What it does
8
+
9
+ Every worker thread Harper starts evaluates the plugin. Each one renders `datadog.yaml` from the environment, takes a pid lock per agent so the node runs one agent pair rather than one per thread, spawns both agents, verifies each answers as the process this node started, and keeps them up. Where Harper supervises processes natively it does the supervising; elsewhere the bundled [process guard](https://github.com/deliciousmonster/harper-process-guard) does, with a detached reaper that stops the agents when the node is killed rather than stopped.
8
10
 
9
11
  ## Install
10
12
 
11
- ```bash
13
+ ```sh
12
14
  npm install @deliciousmonster/datadog-agent-binary
13
15
  ```
14
16
 
15
- npm fetches only the platform package whose `os`/`cpu` match the host, so one agent pair arrives with the install. Two things in the node's own config then decide whether either agent starts.
16
-
17
- ### Name it in the root config
18
-
19
- Harper hands a component a `Scope`, and so calls this plugin at all, only for one the node's root `harper-config.yaml` names. A directory it found by scanning `componentsRoot` loads, serves its resources and supervises nothing. The file is the one `settings_path` names in `~/.harperdb/hdb_boot_properties.file`, and the key is the component directory's own name, because a root entry resolves to `<componentsRoot>/<key>`:
17
+ Two entries in the node's `harper-config.yaml` decide whether anything starts. Name the component, keyed by its directory name:
20
18
 
21
19
  ```yaml
22
20
  datadog-agent-binary: { package: "@deliciousmonster/datadog-agent-binary" }
23
21
  ```
24
22
 
25
- Sixty seconds after the module loads with no plugin call, the component logs the entry it needs and the reason nothing started.
26
-
27
- ### Allowlist both binaries
28
-
29
- Harper only lets a component spawn an executable listed by its exact absolute path in `applications.allowedSpawnCommands`. The other half of that gate, a `name` option on every spawn, the plugin passes itself. Two binaries launch here, not one:
30
-
31
- ```sh
32
- ls -d "$PWD"/node_modules/@deliciousmonster/datadog-agent-binary-*/bin/*
33
- ```
23
+ Allow both binaries by absolute path, and keep `node`, which the reaper is spawned as:
34
24
 
35
25
  ```yaml
36
26
  applications:
@@ -40,99 +30,34 @@ applications:
40
30
  - /app/node_modules/@deliciousmonster/datadog-agent-binary-linux-x86_64/bin/trace-agent
41
31
  ```
42
32
 
43
- A bare command name matches neither one. The paths carry no version, so an upgrade leaves them where they are; on Windows both end `.exe`. Keep `node` in the list too: where Harper does not supervise natively, the bundled guard spawns its reaper as `process.execPath` and then as a bare `node`, and a reaper that cannot start leaves the agents running after the node stops.
44
-
45
- Harper installs with `--ignore-scripts`, which costs this package nothing. `applications.allowInstallScripts` can stay off.
33
+ `ls -d "$PWD"/node_modules/@deliciousmonster/datadog-agent-binary-*/bin/*` prints the paths for the host. On Windows both end in `.exe`. A bare command name matches neither.
46
34
 
47
- ## Configure
35
+ ## Use
48
36
 
49
- The plugin does not configure Datadog. What follows is read from the environment, and `datadog.yaml` is rendered fresh on every worker start, so editing that file changes nothing.
37
+ Configuration is the environment; `datadog.yaml` is rewritten on every start, so editing it changes nothing.
50
38
 
51
39
  | Variable | Effect |
52
40
  | --- | --- |
53
- | `DD_API_KEY` | Measured on 7.82.1: without it the core agent starts and collects while the intake refuses every payload with a 403, and the trace-agent exits at once with "you must specify an API Key", binding no receiver. |
54
- | `DD_SITE` | Destination site, e.g. `datadoghq.eu`. Datadog's own default is `datadoghq.com`. |
41
+ | `DD_API_KEY` | Required. Without it the trace-agent exits at once and the intake refuses the core agent's payloads. |
42
+ | `DD_SITE` | Destination site. Datadog's default is `datadoghq.com`. |
55
43
  | `DD_ENV` | The `env` tag on everything sent. |
56
44
  | `DD_APM_RECEIVER_PORT` | Where `dd-trace` posts spans. Default 8126. |
57
- | `DD_EXPVAR_PORT` | The core agent's expvar. Default 5000. |
58
- | `DD_APM_DEBUG_PORT` | The trace-agent's own expvar. Default 5012. |
59
-
60
- `DD_API_KEY` and `DD_SITE` are never written to disk; both agents read them from the inherited environment. Those two and `DD_ENV` are also part of the fingerprint each agent's PID lock carries, so changing one makes the next worker start take the lock and SIGTERM the agent still running under the old value.
61
-
62
- Setting a port to `0` turns that endpoint off, and each one is load-bearing. Without the receiver `dd-trace` drops every span; without either expvar nothing can show that the process holding the port is the one this node started, and startup verification refuses rather than reporting healthy.
45
+ | `DD_EXPVAR_PORT`, `DD_APM_DEBUG_PORT` | The agents' expvar ports, 5000 and 5012. Verification reads them; `0` turns one off and verification refuses. |
63
46
 
64
- ## Diagnose
47
+ `GET /DatadogStatus/`, under Harper's own auth, reports which supervision is in charge, whether the API key is set, whether each agent verified and why not, and how far a span got: `delivery.verdict` is `delivering`, `rejected`, `traces-unconfirmed` or `idle`. Its counters are the trace-agent's own one-minute window, so read it twice.
65
48
 
66
- Everything the plugin writes lands under `<rootPath>/datadog/<component directory>/`, with `rootPath` read from the node's own config chain, or from `ROOTPATH` where that is absolute. When no root resolves it falls back to `~/.harper-datadog/<component directory>/`. Under either root:
49
+ Everything the plugin writes sits under `<rootPath>/datadog/datadog-agent-binary/`: `datadog.yaml`, `conf.d/`, the agents' logs in `logs/`, and the locks in `pids/`. A lock a killed node left behind is safe to delete.
67
50
 
68
- | Path | What it holds |
69
- | --- | --- |
70
- | `datadog.yaml` | The config both agents read. |
71
- | `conf.d/` | The core checks this platform gets. Without them the core agent runs, reports healthy and collects no host metrics. |
72
- | `logs/agent.log`, `logs/trace-agent.log` | The agents' own logs. `log_to_console` is off, so none of this reaches the container's stdout. |
73
- | `logs/reaper.log` | The guard's reaper, where Harper is not supervising natively. |
74
- | `pids/` | One lock per agent, which is what holds a node to one agent pair rather than one trace-agent per worker thread. Clear it when a killed node leaves a stale lock behind. |
75
-
76
- The directory is named for the component, not just `datadog`: two installed copies sharing one `pids/` would share one lock.
51
+ ## Platforms
77
52
 
78
- `GET /DatadogStatus/` is the plugin's one resource and takes Harper's own auth. It re-reads process state and the trace-agent's delivery counters on each request rather than replaying what boot found. Read in this order:
53
+ Linux x86_64 and arm64, macOS arm64, Windows x86_64. Windows arm64 waits on Chocolatey; macOS x86_64 has no GitHub runner left to build on.
79
54
 
80
- - `supervision` is `harper` when the node's `Scope` carries the process sidecar API, `guard` when the bundled guard is holding the agents up instead.
81
- - `apiKey` is `set` or `MISSING`, never the value.
82
- - `processes[].verified` is a verdict on identity, not on liveness. The trace-agent's is taken by reading its expvar off the debug port and comparing the pid published there against the pid this node spawned, so something else holding the receiver port fails it rather than passing as healthy. `verifyDetail` names the case.
83
- - `delivery.verdict` is how far a span got. `delivering` and `rejected` are evidence either way; `traces-unconfirmed` means the stats hop landed and the trace hop is unproven. Every counter behind it is a one-minute window the agent resets, so read it twice before believing it.
55
+ ## To do
84
56
 
85
- The agents answer directly too, which is the check that does not depend on the plugin:
86
-
87
- ```sh
88
- curl -s http://127.0.0.1:8126/info # the APM receiver, at DD_APM_RECEIVER_PORT
89
- curl -s http://127.0.0.1:5000/debug/vars # the core agent's expvar, at DD_EXPVAR_PORT
90
- curl -sk https://127.0.0.1:5012/debug/vars # the trace-agent's expvar, at DD_APM_DEBUG_PORT
91
- ```
92
-
93
- The last takes `-k` because the trace-agent serves its debug port under the self-signed IPC certificate it writes into `run/`.
94
-
95
- ## Supported platforms
96
-
97
- | OS | Architecture | Status |
98
- | --- | --- | --- |
99
- | Linux | x86_64 | yes |
100
- | Linux | arm64 | yes |
101
- | Windows | x86_64 | yes |
102
- | Windows | arm64 | no |
103
- | macOS | x86_64 | no |
104
- | macOS | arm64 | yes |
105
-
106
- Windows arm64 waits on [Chocolatey](https://chocolatey.org) supporting arm64 natively. macOS x86_64 is out because GitHub retired the Intel runner, and a target with no leg in the release matrix publishes an optional dependency npm skips in silence.
107
-
108
- ## Building from source (maintainers)
109
-
110
- This is how the published binaries are made; consumers do not need it. The build CLI is not in the published tarball, so it runs from a checkout, and it shells out to `dda`, `go` and `pip`, which belong in a developer shell or a CI runner rather than inside a Harper-managed process.
111
-
112
- ```bash
113
- npm run build-agent # current platform, at the version .datadog-agent-version pins
114
- node dist/src/cli.js platforms # supported platforms
115
- node dist/src/cli.js version # latest upstream version
116
-
117
- # a version other than the pin
118
- npm run build && node dist/src/cli.js build --datadog-version 7.50.0
119
- ```
120
-
121
- Requires Go 1.23, Python 3.12, CMake, Git, a C toolchain, and the Node in `engines` (22.18+ or 24+).
122
-
123
- Output goes to `build/<platform>/` under the directory you run from: `src/` is the clone, `go/` the GOPATH it is symlinked into, `bin/` the built binaries. No flag moves it, because `scripts/create-platform-packages.js` reads the binaries back out of that path.
124
-
125
- Publishing is gated on the packed tarball rather than the working tree: both binaries present in every platform package, each carrying its required symbol and free of the Go build tag `--build-exclude` is there to drop.
126
-
127
- ```bash
128
- npm test # component and e2e tiers
129
- npm run typecheck
130
- npm run test:binaries # needs real binaries from a prior build-agent
131
- npm run test:live # boots a real node; released Harper is pinned at 5.2.9, and the
132
- # native-supervision row needs DD_LIVE_HARPER_NATIVE set to a
133
- # Harper worktree whose Scope carries scope.processes
134
- ```
57
+ - Native supervision through Harper's `scope.processes` is proven against a Harper branch, not a release.
58
+ - The Windows leg proves the binaries bind and serve, not the supervision equivalence property. `AGENTS.md` has the reason.
59
+ - `latest` on npm names a prerelease until 7.82.1 ships; install `@next` meanwhile.
135
60
 
136
61
  ## License
137
62
 
138
- Apache License 2.0. The agent binaries built and distributed here are Apache 2.0 as specified in the [Datadog Agent repository](https://github.com/DataDog/datadog-agent), and the datadog-agent source is copyright Datadog, Inc.
63
+ Apache-2.0. The agent binaries are Datadog's, Apache-2.0, built from the pinned release of [datadog-agent](https://github.com/DataDog/datadog-agent).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deliciousmonster/datadog-agent-binary",
3
- "version": "7.82.1-next.1",
3
+ "version": "7.82.1-next.2",
4
4
  "description": "Harper component that runs the Datadog trace-agent and core-agent alongside a node, with pre-built binaries installed per platform",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -38,7 +38,7 @@
38
38
  "author": "",
39
39
  "license": "Apache-2.0",
40
40
  "dependencies": {
41
- "@deliciousmonster/harper-process-guard": "0.1.0-next.1"
41
+ "@deliciousmonster/harper-process-guard": "0.1.0-next.2"
42
42
  },
43
43
  "devDependencies": {
44
44
  "@types/node": "^26.0.0",
@@ -68,10 +68,10 @@
68
68
  },
69
69
  "homepage": "https://github.com/deliciousmonster/datadog-agent-binary#readme",
70
70
  "optionalDependencies": {
71
- "@deliciousmonster/datadog-agent-binary-linux-x86_64": "7.82.1-next.1",
72
- "@deliciousmonster/datadog-agent-binary-linux-arm64": "7.82.1-next.1",
73
- "@deliciousmonster/datadog-agent-binary-macos-arm64": "7.82.1-next.1",
74
- "@deliciousmonster/datadog-agent-binary-windows-x86_64": "7.82.1-next.1"
71
+ "@deliciousmonster/datadog-agent-binary-linux-x86_64": "7.82.1-next.2",
72
+ "@deliciousmonster/datadog-agent-binary-linux-arm64": "7.82.1-next.2",
73
+ "@deliciousmonster/datadog-agent-binary-macos-arm64": "7.82.1-next.2",
74
+ "@deliciousmonster/datadog-agent-binary-windows-x86_64": "7.82.1-next.2"
75
75
  },
76
76
  "lint-staged": {
77
77
  "*.{ts,js,json}": [