@julr/otel-instrumentation-clickhouse 1.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 +83 -0
- package/package.json +84 -0
package/README.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# OpenTelemetry ClickHouse Instrumentation
|
|
2
|
+
|
|
3
|
+
This module provides automatic instrumentation and tracing for [ClickHouse](https://clickhouse.com/) in Node.js applications using the official [@clickhouse/client](https://www.npmjs.com/package/@clickhouse/client) package
|
|
4
|
+
|
|
5
|
+
Compatible with OpenTelemetry JS API and SDK `1.0+`.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @julr/otel-instrumentation-clickhouse
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
### Supported Versions
|
|
14
|
+
|
|
15
|
+
- [`@clickhouse/client`](https://www.npmjs.com/package/@clickhouse/client) versions `>=1.0.0`
|
|
16
|
+
- [`@clickhouse/client-web`](https://www.npmjs.com/package/@clickhouse/client-web) versions `>=1.0.0`
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
const { ClickHouseInstrumentation } = require('@julr/otel-instrumentation-clickhouse');
|
|
22
|
+
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
|
|
23
|
+
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
|
|
24
|
+
|
|
25
|
+
const provider = new NodeTracerProvider();
|
|
26
|
+
provider.register();
|
|
27
|
+
|
|
28
|
+
registerInstrumentations({
|
|
29
|
+
instrumentations: [
|
|
30
|
+
new ClickHouseInstrumentation({
|
|
31
|
+
// optional params
|
|
32
|
+
// maxQueryLength: 2048,
|
|
33
|
+
// requireParentSpan: false,
|
|
34
|
+
// suppressInternalInstrumentation: true,
|
|
35
|
+
}),
|
|
36
|
+
],
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Configuration Options
|
|
41
|
+
|
|
42
|
+
| Option | Type | Default | Description |
|
|
43
|
+
| --------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `maxQueryLength` | number | 2048 | Maximum length of the query to include in the span. Queries longer than this will be truncated. Set to `0` to disable query capture. |
|
|
45
|
+
| `requireParentSpan` | boolean | false | Whether to require a parent span to create child spans. When `true`, ClickHouse spans will only be created if there is an active parent span. |
|
|
46
|
+
| `suppressInternalInstrumentation` | boolean | true | Whether to suppress internal HTTP instrumentation. When `true`, HTTP spans for ClickHouse requests will not be created by `@opentelemetry/instrumentation-http`. |
|
|
47
|
+
|
|
48
|
+
## Instrumented Methods
|
|
49
|
+
|
|
50
|
+
The following ClickHouse client methods are automatically instrumented:
|
|
51
|
+
|
|
52
|
+
- `query()` - Execute SELECT queries
|
|
53
|
+
- `insert()` - Insert data into tables
|
|
54
|
+
- `command()` - Execute DDL commands (CREATE, ALTER, etc.)
|
|
55
|
+
- `exec()` - Execute raw queries
|
|
56
|
+
|
|
57
|
+
## Span Attributes
|
|
58
|
+
|
|
59
|
+
This instrumentation sets the following span attributes following [OpenTelemetry Semantic Conventions for Database](https://opentelemetry.io/docs/specs/semconv/database/database-spans/):
|
|
60
|
+
|
|
61
|
+
| Attribute | Description |
|
|
62
|
+
| -------------------- | ----------------------------------------------- |
|
|
63
|
+
| `db.system.name` | Always set to `clickhouse` |
|
|
64
|
+
| `db.operation.name` | The operation type (`query`, `insert`, etc.) |
|
|
65
|
+
| `db.query.text` | The SQL query (truncated if exceeds max length) |
|
|
66
|
+
| `db.namespace` | The database name |
|
|
67
|
+
| `db.collection.name` | The table name (when available) |
|
|
68
|
+
| `server.address` | The ClickHouse server hostname |
|
|
69
|
+
| `server.port` | The ClickHouse server port |
|
|
70
|
+
|
|
71
|
+
## Useful Links
|
|
72
|
+
|
|
73
|
+
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
|
|
74
|
+
- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
|
|
75
|
+
|
|
76
|
+
## License
|
|
77
|
+
|
|
78
|
+
Apache 2.0 - See [LICENSE][license-url] for more information.
|
|
79
|
+
|
|
80
|
+
[license-url]: https://github.com/julr/otel-instrumentation-clickhouse/blob/main/LICENSE
|
|
81
|
+
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
|
|
82
|
+
[npm-url]: https://www.npmjs.com/package/@julr/otel-instrumentation-clickhouse
|
|
83
|
+
[npm-img]: https://badge.fury.io/js/%40julr%2Fotel-instrumentation-clickhouse.svg
|
package/package.json
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@julr/otel-instrumentation-clickhouse",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "OpenTelemetry automatic instrumentation for ClickHouse client",
|
|
5
|
+
"main": "./dist/index.js",
|
|
6
|
+
"module": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"type": "module",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"import": "./dist/index.js",
|
|
12
|
+
"types": "./dist/index.d.ts"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist"
|
|
17
|
+
],
|
|
18
|
+
"scripts": {
|
|
19
|
+
"build": "tsc",
|
|
20
|
+
"typecheck": "tsc --noEmit",
|
|
21
|
+
"format": "oxfmt",
|
|
22
|
+
"lint": "oxlint",
|
|
23
|
+
"lint:fix": "oxlint --fix",
|
|
24
|
+
"prepublishOnly": "pnpm run build",
|
|
25
|
+
"release": "release-it"
|
|
26
|
+
},
|
|
27
|
+
"release-it": {
|
|
28
|
+
"git": {
|
|
29
|
+
"commitMessage": "chore: release v${version}"
|
|
30
|
+
},
|
|
31
|
+
"github": {
|
|
32
|
+
"release": true
|
|
33
|
+
},
|
|
34
|
+
"hooks": {
|
|
35
|
+
"before:init": [
|
|
36
|
+
"pnpm run lint",
|
|
37
|
+
"pnpm run typecheck"
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
},
|
|
41
|
+
"keywords": [
|
|
42
|
+
"opentelemetry",
|
|
43
|
+
"otel",
|
|
44
|
+
"instrumentation",
|
|
45
|
+
"clickhouse",
|
|
46
|
+
"tracing",
|
|
47
|
+
"observability",
|
|
48
|
+
"monitoring"
|
|
49
|
+
],
|
|
50
|
+
"author": "Julien Ripouteau <julien@ripouteau.com>",
|
|
51
|
+
"license": "Apache-2.0",
|
|
52
|
+
"publishConfig": {
|
|
53
|
+
"access": "public"
|
|
54
|
+
},
|
|
55
|
+
"repository": {
|
|
56
|
+
"type": "git",
|
|
57
|
+
"url": "git+https://github.com/julien-r44/otel-instrumentation-clickhouse.git"
|
|
58
|
+
},
|
|
59
|
+
"bugs": {
|
|
60
|
+
"url": "https://github.com/julien-r44/otel-instrumentation-clickhouse/issues"
|
|
61
|
+
},
|
|
62
|
+
"homepage": "https://github.com/julien-r44/otel-instrumentation-clickhouse#readme",
|
|
63
|
+
"packageManager": "pnpm@10.26.2",
|
|
64
|
+
"engines": {
|
|
65
|
+
"node": ">=18"
|
|
66
|
+
},
|
|
67
|
+
"peerDependencies": {
|
|
68
|
+
"@opentelemetry/api": "^1.0.0"
|
|
69
|
+
},
|
|
70
|
+
"dependencies": {
|
|
71
|
+
"@opentelemetry/core": "^2.2.0",
|
|
72
|
+
"@opentelemetry/instrumentation": "^0.208.0"
|
|
73
|
+
},
|
|
74
|
+
"devDependencies": {
|
|
75
|
+
"@julr/tooling-configs": "^5.0.0",
|
|
76
|
+
"@opentelemetry/api": "^1.9.0",
|
|
77
|
+
"@types/node": "^25.0.3",
|
|
78
|
+
"oxfmt": "^0.21.0",
|
|
79
|
+
"oxlint": "^1.36.0",
|
|
80
|
+
"oxlint-tsgolint": "^0.10.0",
|
|
81
|
+
"release-it": "^19.2.2",
|
|
82
|
+
"typescript": "^5.9.3"
|
|
83
|
+
}
|
|
84
|
+
}
|