@saidsef/tracing-node 4.1.0 → 4.2.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 (2) hide show
  1. package/README.md +32 -26
  2. package/package.json +22 -20
package/README.md CHANGED
@@ -31,38 +31,27 @@ Effortlessly supercharge your applications with world-class distributed tracing!
31
31
  - ...
32
32
  - Profit?
33
33
 
34
- ## Instalation
34
+ ## Where the traces go
35
35
 
36
- ```
37
- npm install @saidsef/tracing-node --save
38
- ```
36
+ `setupTracing` exports OTLP over gRPC, so any OpenTelemetry-compatible collector or backend will take it - point `url` at yours.
39
37
 
40
- ## Upgrading to 4.0.0
38
+ 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:
41
39
 
42
- **Breaking change: spans now carry the stable OpenTelemetry semantic conventions.**
40
+ ```javascript
41
+ setupTracing({serviceName: 'my-service', url: 'http://alloy:4317'});
42
+ ```
43
43
 
44
- The upstream instrumentations ([open-telemetry/opentelemetry-js-contrib#3585](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/3585)) dropped the legacy attributes and removed the `OTEL_SEMCONV_STABILITY_OPT_IN` escape hatch, so there is no way to keep the old names. The public API of `setupTracing` / `stopTracing` is unchanged - no code changes are required - but any dashboard, alert or processor keyed on the old attribute names must be updated.
44
+ 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.
45
45
 
46
- | Removed | Replacement | Affected spans |
47
- |---------|-------------|----------------|
48
- | `http.method` | `http.request.method` | HTTP |
49
- | `http.status_code` | `http.response.status_code` | HTTP, AWS SDK |
50
- | `http.url` | `url.full` | HTTP |
51
- | `http.target` | `url.path` + `url.query` | HTTP |
52
- | `http.scheme` | `url.scheme` | HTTP |
53
- | `http.user_agent` | `user_agent.original` | HTTP |
54
- | `http.client_ip` | `client.address` | HTTP |
55
- | `http.flavor` | `network.protocol.version` | HTTP |
56
- | `net.peer.name` | `server.address` | HTTP, IORedis |
57
- | `net.peer.port` | `server.port` | HTTP, IORedis |
58
- | `db.system` | `db.system.name` | IORedis, DynamoDB |
59
- | `db.statement` | `db.query.text` | IORedis, DynamoDB |
60
- | `db.operation` | `db.operation.name` | IORedis, DynamoDB |
61
- | `db.connection_string` | none | IORedis |
46
+ ## Instalation
62
47
 
63
- Server-side HTTP metrics also move from `http.server.duration` (milliseconds) to `http.server.request.duration` (seconds), and the client equivalents likewise.
48
+ ```
49
+ npm install @saidsef/tracing-node --save
50
+ ```
51
+
52
+ ## Upgrading
64
53
 
65
- `peer.service` is unchanged, so Tempo/Grafana service graphs keep working as before. IORedis spans also gain `db.operation.name`, which distinguishes `MULTI`/`PIPELINE` commands.
54
+ 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.
66
55
 
67
56
  ## Usage
68
57
 
@@ -91,9 +80,26 @@ setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'
91
80
  | enableFsInstrumentation | boolean | enable FS instrumentation | No | `false` |
92
81
  | enableDnsInstrumentation | boolean | enable DNS instrumentation | No | `false` |
93
82
 
83
+ ## Documentation
84
+
85
+ Full documentation is in the [`docs/`](./docs) directory and built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
86
+
87
+ Live docs: [tracing-node.readthedocs.io](https://tracing-node.readthedocs.io/)
88
+
89
+ | Page | Contents |
90
+ |------|----------|
91
+ | [Architecture](./docs/architecture.md) | The pipeline `setupTracing` builds, and how the service graph is fed |
92
+ | [Configuration](./docs/usage.md) | Options, environment variables, initialisation order and shutdown |
93
+ | [Instrumentation](./docs/instrumentation.md) | Each instrumentation, and the attributes it emits |
94
+ | [Deployment](./docs/deployment.md) | Running instrumented services in containers and Kubernetes |
95
+ | [Testing](./docs/testing.md) | The unit tests and the end to end harness |
96
+ | [Troubleshooting](./docs/troubleshooting.md) | Symptoms, causes and fixes |
97
+
98
+ Build them locally with `npm run build-docs`, which renders the site into `site/`.
99
+
94
100
  ## Source
95
101
 
96
- Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-nodec/fork). Fork us!
102
+ Our latest and greatest source of `tracing-node` can be found on [GitHub](https://github.com/saidsef/tracing-node/fork). Fork us!
97
103
 
98
104
  ## Contributing
99
105
 
package/package.json CHANGED
@@ -1,12 +1,14 @@
1
1
  {
2
2
  "name": "@saidsef/tracing-node",
3
- "version": "4.1.0",
3
+ "version": "4.2.0",
4
4
  "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
5
5
  "main": "libs/index.mjs",
6
6
  "scripts": {
7
7
  "test": "node --trace-warnings --test --report-uncaught-exception libs/index.test.mjs",
8
8
  "lint": "eslint .",
9
- "rebuild": "rm -rfv node_modules/ package-lock.json && npm install --prod --omit=dev"
9
+ "rebuild": "rm -rfv node_modules/ package-lock.json && npm install --prod --omit=dev",
10
+ "build-docs": "podman run --rm -v .:/docs docker.io/squidfunk/mkdocs-material:9 build",
11
+ "clean-docs": "rm -rf site"
10
12
  },
11
13
  "type": "module",
12
14
  "private": false,
@@ -30,32 +32,32 @@
30
32
  },
31
33
  "homepage": "https://github.com/saidsef/tracing-node#readme",
32
34
  "dependencies": {
33
- "@opentelemetry/api": "^1.9.0",
34
- "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
35
- "@opentelemetry/instrumentation": "^0.221.0",
36
- "@opentelemetry/instrumentation-aws-sdk": "^0.76.0",
37
- "@opentelemetry/instrumentation-connect": "^0.64.0",
38
- "@opentelemetry/instrumentation-dns": "^0.64.0",
39
- "@opentelemetry/instrumentation-express": "^0.69.0",
40
- "@opentelemetry/instrumentation-fs": "^0.40.0",
41
- "@opentelemetry/instrumentation-http": "^0.221.0",
42
- "@opentelemetry/instrumentation-ioredis": "^0.69.0",
43
- "@opentelemetry/instrumentation-pino": "^0.67.0",
44
- "@opentelemetry/instrumentation-undici": "^0.31.0",
45
- "@opentelemetry/resources": "^2.10.0",
46
- "@opentelemetry/sdk-trace-base": "^2.10.0",
47
- "@opentelemetry/sdk-trace-node": "^2.10.0",
35
+ "@opentelemetry/api": "^1.9.1",
36
+ "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
37
+ "@opentelemetry/instrumentation": "^0.222.0",
38
+ "@opentelemetry/instrumentation-aws-sdk": "^0.77.0",
39
+ "@opentelemetry/instrumentation-connect": "^0.65.0",
40
+ "@opentelemetry/instrumentation-dns": "^0.65.0",
41
+ "@opentelemetry/instrumentation-express": "^0.70.0",
42
+ "@opentelemetry/instrumentation-fs": "^0.41.0",
43
+ "@opentelemetry/instrumentation-http": "^0.222.0",
44
+ "@opentelemetry/instrumentation-ioredis": "^0.70.0",
45
+ "@opentelemetry/instrumentation-pino": "^0.68.0",
46
+ "@opentelemetry/instrumentation-undici": "^0.32.0",
47
+ "@opentelemetry/resources": "^2.11.0",
48
+ "@opentelemetry/sdk-trace-base": "^2.11.0",
49
+ "@opentelemetry/sdk-trace-node": "^2.11.0",
48
50
  "@opentelemetry/semantic-conventions": "^1.43.0",
49
51
  "opentelemetry-instrumentation-elasticsearch": "^0.41.0"
50
52
  },
51
53
  "devDependencies": {
52
- "eslint": "^10.8.0"
54
+ "eslint": "^10.10.0"
53
55
  },
54
56
  "overrides": {
55
57
  "protobufjs": "^7.5.3",
56
- "@opentelemetry/core": "^2.10.0"
58
+ "@opentelemetry/core": "^2.11.0"
57
59
  },
58
60
  "allowScripts": {
59
- "protobufjs@7.6.5": true
61
+ "protobufjs@7.6.6": true
60
62
  }
61
63
  }