@saidsef/tracing-node 5.0.0 → 5.0.1
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 +26 -85
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,32 +1,18 @@
|
|
|
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
18
|
- NodeJS
|
|
@@ -34,87 +20,42 @@ Effortlessly supercharge your applications with world-class distributed tracing!
|
|
|
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:
|
|
42
|
-
|
|
43
|
-
```javascript
|
|
44
|
-
setupTracing({serviceName: 'my-service', url: 'http://alloy:4317'});
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
The W3C Trace Context propagation this library registers is what lets Tempo pair a caller's client span with the callee's server span, which is what a service graph is built from.
|
|
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.
|
|
52
|
-
|
|
53
|
-
## Instalation
|
|
23
|
+
## Installation
|
|
54
24
|
|
|
55
|
-
```
|
|
25
|
+
```shell
|
|
56
26
|
npm install @saidsef/tracing-node --save
|
|
57
27
|
```
|
|
58
28
|
|
|
59
|
-
## Upgrading
|
|
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.
|
|
62
|
-
|
|
63
29
|
## Usage
|
|
64
30
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
Env vars:
|
|
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 |
|
|
73
|
-
|
|
74
|
-
Function args
|
|
75
|
-
```
|
|
31
|
+
```javascript
|
|
76
32
|
import { setupTracing } from '@saidsef/tracing-node';
|
|
33
|
+
|
|
77
34
|
setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'});
|
|
78
35
|
```
|
|
79
36
|
|
|
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` |
|
|
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.
|
|
94
38
|
|
|
95
39
|
## Documentation
|
|
96
40
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
Live docs: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/)
|
|
41
|
+
The pages below are the manual. Their sources are in [`docs/`](./docs), and `npm run build-docs` renders the site into `site/`.
|
|
100
42
|
|
|
101
43
|
| Page | Contents |
|
|
102
44
|
|------|----------|
|
|
103
|
-
| [
|
|
104
|
-
| [
|
|
105
|
-
| [
|
|
106
|
-
| [
|
|
107
|
-
| [
|
|
108
|
-
| [
|
|
109
|
-
|
|
110
|
-
Build them locally with `npm run build-docs`, which renders the site into `site/`.
|
|
45
|
+
| [Overview](https://tracing-node.readthedocs.io/en/latest/) | What the library does, the feature set and the requirements |
|
|
46
|
+
| [Architecture](https://tracing-node.readthedocs.io/en/latest/architecture/) | The pipeline `setupTracing` builds, and how the service graph is fed |
|
|
47
|
+
| [Configuration](https://tracing-node.readthedocs.io/en/latest/usage/) | Every option, the environment variables, initialisation order and shutdown |
|
|
48
|
+
| [Instrumentation](https://tracing-node.readthedocs.io/en/latest/instrumentation/) | Each instrumentation, and the attributes it emits |
|
|
49
|
+
| [Deployment](https://tracing-node.readthedocs.io/en/latest/deployment/) | Running instrumented services in containers and Kubernetes |
|
|
50
|
+
| [Testing](https://tracing-node.readthedocs.io/en/latest/testing/) | The unit tests and the end to end harness |
|
|
51
|
+
| [Troubleshooting](https://tracing-node.readthedocs.io/en/latest/troubleshooting/) | Symptoms, causes and fixes |
|
|
111
52
|
|
|
112
|
-
##
|
|
53
|
+
## Upgrading
|
|
113
54
|
|
|
114
|
-
|
|
55
|
+
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
56
|
|
|
116
57
|
## Contributing
|
|
117
58
|
|
|
118
|
-
|
|
59
|
+
Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-node/fork). Fork us!
|
|
119
60
|
|
|
120
|
-
Please read the official [Contribution Guide](./CONTRIBUTING.md) for more information on how you can contribute.
|
|
61
|
+
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.
|