@saidsef/tracing-node 5.0.0 → 6.0.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.
- package/README.md +37 -83
- package/deployment/base/job.yml +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,120 +1,74 @@
|
|
|
1
|
-
#
|
|
1
|
+
# OpenTelemetry Wrapper for Tracing Node Applications
|
|
2
2
|
|
|
3
|
-
[](
|
|
4
|
-
[](
|
|
3
|
+
[](https://github.com/saidsef/tracing-node/actions/workflows/pr.yml)
|
|
4
|
+
[](https://github.com/saidsef/tracing-node/actions/workflows/release.yml)
|
|
5
|
+
[](https://tracing-node.readthedocs.io/en/latest/)
|
|
5
6
|
|
|
6
7
|
 
|
|
7
8
|
|
|
8
9
|
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
| Feature | Description |
|
|
16
|
-
|---------|-------------|
|
|
17
|
-
| HTTP/HTTPS instrumentation | Automatic service detection |
|
|
18
|
-
| fetch/undici instrumentation | Outgoing `globalThis.fetch` calls |
|
|
19
|
-
| Express.js support | Framework instrumentation |
|
|
20
|
-
| Elasticsearch client | Database instrumentation |
|
|
21
|
-
| IORedis client | Cache instrumentation |
|
|
22
|
-
| AWS SDK | Cloud service instrumentation |
|
|
23
|
-
| Pino logger | Integration with trace/span IDs |
|
|
24
|
-
| Node runtime metrics | Event loop, garbage collection, heap |
|
|
25
|
-
| Log export | Pino records over OTLP, correlated by trace |
|
|
26
|
-
| RED metrics | Request duration histograms over OTLP |
|
|
27
|
-
| DNS/FS instrumentation | Optional monitoring |
|
|
28
|
-
| Resource detection | Host, OS, process, container |
|
|
29
|
-
| W3C Trace Context | Standard propagation |
|
|
11
|
+
**Traces, metrics and logs from one function call.** Add two lines to a service, and its requests, its calls to Redis, Elasticsearch, AWS and other services, its runtime counters and its Pino log records all arrive at your collector, already correlated by trace id and stitched into a service graph.
|
|
12
|
+
|
|
13
|
+
`@saidsef/tracing-node` wraps the OpenTelemetry Node SDK. One call to `setupTracing` builds the tracer, meter and logger providers, registers them globally, and turns on a fixed set of instrumentations, so an application gets all three signals without assembling exporters, span processors, resource detectors and instrumentation packages itself. A second call logs a warning and returns the tracer that already exists, which makes initialisation idempotent.
|
|
14
|
+
|
|
15
|
+
Full documentation: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/).
|
|
30
16
|
|
|
31
17
|
## Prerequisites
|
|
32
|
-
- NodeJS
|
|
18
|
+
- NodeJS >= 24.0.0
|
|
33
19
|
- Observability
|
|
34
20
|
- ...
|
|
35
21
|
- Profit?
|
|
36
22
|
|
|
37
|
-
##
|
|
38
|
-
|
|
39
|
-
`setupTracing` exports OTLP over gRPC, so any OpenTelemetry-compatible collector or backend will take it - point `url` at yours.
|
|
40
|
-
|
|
41
|
-
If you do not have one yet, [grafana-loki-on-k8s](https://github.com/saidsef/grafana-loki-on-k8s) is a companion project that deploys the full LGTM+ stack - Grafana, Prometheus, Mimir, Loki, Tempo, Pyroscope, Alloy and Beyla - to Kubernetes with `kubectl apply -k ./deployment`, broken into small composable manifests rather than a single opaque chart. Send traces to its Alloy OTLP receiver and they land in Tempo, with the metrics-generator turning them into RED and service-graph metrics in Mimir:
|
|
23
|
+
## Installation
|
|
42
24
|
|
|
43
|
-
```
|
|
44
|
-
|
|
25
|
+
```shell
|
|
26
|
+
npm install @saidsef/tracing-node --save
|
|
45
27
|
```
|
|
46
28
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Metrics go to the same endpoint by default and land in Mimir. They are recorded before the sampler runs, so they stay complete however far trace volume is turned down.
|
|
50
|
-
|
|
51
|
-
Pino log records go to the same endpoint and land in Loki, each carrying the trace and span id of the request that wrote it. No log agent or file scraping sits in between.
|
|
29
|
+
## Usage
|
|
52
30
|
|
|
53
|
-
|
|
31
|
+
```javascript
|
|
32
|
+
import { setupTracing } from '@saidsef/tracing-node';
|
|
54
33
|
|
|
55
|
-
|
|
56
|
-
npm install @saidsef/tracing-node --save
|
|
34
|
+
setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'});
|
|
57
35
|
```
|
|
58
36
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
Breaking changes and the attribute renames they bring are recorded in the [release notes](https://github.com/saidsef/tracing-node/releases) for the version concerned.
|
|
37
|
+
`serviceName` and `url` are required, and both fall back to the `SERVICE_NAME` and `ENDPOINT` environment variables. `setupTracing` has to run before the application imports the libraries being traced.
|
|
62
38
|
|
|
63
|
-
##
|
|
39
|
+
## Collector and backend
|
|
64
40
|
|
|
65
|
-
|
|
41
|
+
The exporter speaks OTLP over gRPC, so any OpenTelemetry-compatible collector accepts all three signals. Point `url` at yours.
|
|
66
42
|
|
|
67
|
-
|
|
68
|
-
| Environment Variable | Description | Required |
|
|
69
|
-
|-----------------------|----------------------------| --------- |
|
|
70
|
-
| CONTAINER_NAME/HOSTNAME| Container or pod hostname | No |
|
|
71
|
-
| ENDPOINT | Tracing collector endpoint | Yes |
|
|
72
|
-
| SERVICE_NAME | Service/application name | Yes |
|
|
43
|
+
[**grafana-loki-on-k8s**](https://github.com/saidsef/grafana-loki-on-k8s) is the companion stack, and the one the end to end harness in [`test/e2e/`](./test/e2e) targets. It deploys Grafana, Prometheus, Mimir, Loki, Tempo, Pyroscope, Alloy and Beyla to Kubernetes as small composable manifests.
|
|
73
44
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'});
|
|
45
|
+
```shell
|
|
46
|
+
git clone https://github.com/saidsef/grafana-loki-on-k8s
|
|
47
|
+
kubectl apply -k grafana-loki-on-k8s/deployment
|
|
78
48
|
```
|
|
79
49
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
| Name | Type | Description| Required | Default |
|
|
83
|
-
|----- | ---- | ------------- | ----- | ---- |
|
|
84
|
-
| hostname | string | container / pod hostname | No | `hostname` |
|
|
85
|
-
| serviceName | string | service / application name | Yes | `n/a` |
|
|
86
|
-
| url | string | tracing endpoint i.e. `<schema>://<host>:<port>` | Yes | `n/a` |
|
|
87
|
-
| enableFsInstrumentation | boolean | enable FS instrumentation | No | `false` |
|
|
88
|
-
| enableDnsInstrumentation | boolean | enable DNS instrumentation | No | `false` |
|
|
89
|
-
| enableMetrics | boolean | export metrics as well as traces | No | `true` |
|
|
90
|
-
| metricsUrl | string | metrics endpoint, when it differs from `url` | No | `url` |
|
|
91
|
-
| metricExportIntervalMillis | number | how often metrics are exported | No | `60000` |
|
|
92
|
-
| enableLogs | boolean | send Pino log records over OTLP | No | `true` |
|
|
93
|
-
| logsUrl | string | logs endpoint, when it differs from `url` | No | `url` |
|
|
50
|
+
Traces sent to its Alloy OTLP receiver on port 4317 land in Tempo, log records in Loki and metrics in Mimir. Tempo's metrics generator turns the spans into RED and service graph metrics, which is what the `peer.service` attribute this library sets exists to feed.
|
|
94
51
|
|
|
95
52
|
## Documentation
|
|
96
53
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
Live docs: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/)
|
|
54
|
+
The pages below are the manual. Their sources are in [`docs/`](./docs), and `npm run build-docs` renders the site into `site/`.
|
|
100
55
|
|
|
101
56
|
| Page | Contents |
|
|
102
57
|
|------|----------|
|
|
103
|
-
| [
|
|
104
|
-
| [
|
|
105
|
-
| [
|
|
106
|
-
| [
|
|
107
|
-
| [
|
|
108
|
-
| [
|
|
109
|
-
|
|
110
|
-
Build them locally with `npm run build-docs`, which renders the site into `site/`.
|
|
58
|
+
| [Overview](https://tracing-node.readthedocs.io/en/latest/) | What the library does, the feature set and the requirements |
|
|
59
|
+
| [Architecture](https://tracing-node.readthedocs.io/en/latest/architecture/) | The pipeline `setupTracing` builds, and how the service graph is fed |
|
|
60
|
+
| [Configuration](https://tracing-node.readthedocs.io/en/latest/usage/) | Every option, the environment variables, initialisation order and shutdown |
|
|
61
|
+
| [Instrumentation](https://tracing-node.readthedocs.io/en/latest/instrumentation/) | Each instrumentation, and the attributes it emits |
|
|
62
|
+
| [Deployment](https://tracing-node.readthedocs.io/en/latest/deployment/) | Running instrumented services in containers and Kubernetes |
|
|
63
|
+
| [Testing](https://tracing-node.readthedocs.io/en/latest/testing/) | The unit tests and the end to end harness |
|
|
64
|
+
| [Troubleshooting](https://tracing-node.readthedocs.io/en/latest/troubleshooting/) | Symptoms, causes and fixes |
|
|
111
65
|
|
|
112
|
-
##
|
|
66
|
+
## Upgrading
|
|
113
67
|
|
|
114
|
-
|
|
68
|
+
Breaking changes and the attribute renames they bring are recorded in the [release notes](https://github.com/saidsef/tracing-node/releases) for the version concerned.
|
|
115
69
|
|
|
116
70
|
## Contributing
|
|
117
71
|
|
|
118
|
-
|
|
72
|
+
Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-node/fork). Fork us!
|
|
119
73
|
|
|
120
|
-
Please read the official [Contribution Guide](./CONTRIBUTING.md) for more information on how you can contribute.
|
|
74
|
+
We would :heart: you to contribute by making a [pull request](https://github.com/saidsef/tracing-node/pulls). Please read the official [Contribution Guide](./CONTRIBUTING.md) for more information on how you can contribute.
|
package/deployment/base/job.yml
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@saidsef/tracing-node",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "6.0.0",
|
|
4
4
|
"description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
|
|
5
5
|
"main": "libs/index.mjs",
|
|
6
6
|
"scripts": {
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"author": "Said Sef <saidsef@gmail.com>",
|
|
26
26
|
"license": "Apache-2.0",
|
|
27
27
|
"engines": {
|
|
28
|
-
"node": ">=
|
|
28
|
+
"node": ">= 24.0.0"
|
|
29
29
|
},
|
|
30
30
|
"bugs": {
|
|
31
31
|
"url": "https://github.com/saidsef/tracing-node/issues"
|