@bsb/observable-zipkin 1.0.0 → 1.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.
Files changed (2) hide show
  1. package/README.md +56 -118
  2. package/package.json +7 -4
package/README.md CHANGED
@@ -1,15 +1,13 @@
1
- # BSB Observable Zipkin
1
+ # @bsb/observable-zipkin
2
2
 
3
- Zipkin tracing integration for the Better Service Base (BSB) framework.
3
+ Zipkin tracing integration for BSB. Exports distributed traces to Zipkin and provides optional console logging.
4
4
 
5
- ## Features
5
+ ## Key Features
6
6
 
7
- - Direct Zipkin v2 API integration
8
- - Distributed tracing with OpenTelemetry instrumentation
9
- - Configurable sampling rates
10
- - Batch span export with configurable flush intervals
11
- - Console logging fallback for non-trace observability
12
- - Full TypeScript support
7
+ - Zipkin v2 API export
8
+ - OpenTelemetry-based tracing
9
+ - Configurable sampling and batching
10
+ - Optional console logging for non-trace output
13
11
 
14
12
  ## Installation
15
13
 
@@ -19,137 +17,77 @@ npm install @bsb/observable-zipkin
19
17
 
20
18
  ## Configuration
21
19
 
22
- Add to your BSB configuration file:
20
+ Add the plugin to your BSB configuration file:
23
21
 
24
22
  ```yaml
25
23
  plugins:
26
- observable:
27
- - observable-zipkin
28
-
29
- observable-zipkin:
30
- serviceName: my-service
31
- serviceVersion: 1.0.0
32
-
33
- zipkin:
34
- url: http://localhost:9411/api/v2/spans
35
- # Optional custom headers for authentication
36
- # headers:
37
- # Authorization: Bearer token123
38
-
39
- export:
40
- maxBatchSize: 100
41
- maxQueueSize: 2048
42
- scheduledDelayMillis: 5000
43
-
44
- samplingRate: 1.0 # 1.0 = 100%, 0.5 = 50%
45
-
46
- # Console logging (Zipkin doesn't handle logs/metrics)
47
- console:
48
- enabled: true
49
- logLevel: info # debug | info | warn | error
50
-
51
- # Optional resource attributes
52
- resourceAttributes:
53
- environment: production
54
- region: us-east-1
24
+ observables:
25
+ - plugin: "@bsb/observable-zipkin"
26
+ enabled: true
27
+ config:
28
+ serviceName: "my-service"
29
+ serviceVersion: "1.0.0"
30
+ zipkin:
31
+ url: "http://localhost:9411/api/v2/spans"
32
+ # headers:
33
+ # Authorization: "Bearer token123"
34
+ export:
35
+ maxBatchSize: 100
36
+ maxQueueSize: 2048
37
+ scheduledDelayMillis: 5000
38
+ samplingRate: 1.0
39
+ console:
40
+ enabled: true
41
+ logLevel: "info"
42
+ resourceAttributes:
43
+ environment: "production"
44
+ region: "us-east-1"
55
45
  ```
56
46
 
57
- ## What Gets Exported
58
-
59
- ### Traces (to Zipkin)
60
- - All span lifecycle events (start, end, error)
61
- - Span attributes and context
62
- - Distributed trace propagation
63
- - Exception tracking
64
-
65
- ### Logs (to Console)
66
- - Debug, info, warn, error levels
67
- - Structured logging with trace context
68
- - Configurable log level filtering
69
-
70
- ### Metrics (No-op)
71
- - Zipkin is trace-only, no metrics support
72
- - Use `observable-opentelemetry` or `observable-prometheus` for metrics
47
+ ### Configuration Options
48
+
49
+ | Option | Description | Default |
50
+ |--------|-------------|---------|
51
+ | `serviceName` | Service identifier | `"bsb-service"` |
52
+ | `serviceVersion` | Service version tag | - |
53
+ | `zipkin.url` | Zipkin API endpoint | `"http://localhost:9411/api/v2/spans"` |
54
+ | `zipkin.headers` | Custom HTTP headers | - |
55
+ | `export.maxBatchSize` | Max spans per batch | `100` |
56
+ | `export.maxQueueSize` | Max queued spans | `2048` |
57
+ | `export.scheduledDelayMillis` | Flush interval (ms) | `5000` |
58
+ | `samplingRate` | Sampling probability (0-1) | `1.0` |
59
+ | `console.enabled` | Enable console logs | `true` |
60
+ | `console.logLevel` | Minimum log level | `"info"` |
61
+ | `resourceAttributes` | Custom attributes | `{}` |
73
62
 
74
63
  ## Usage
75
64
 
76
- The plugin automatically integrates with BSB's Observable pattern:
65
+ Once configured, traces are exported automatically:
77
66
 
78
67
  ```typescript
79
- export class MyService extends BSBService<InstanceType<typeof Config>, typeof EventSchemas> {
80
- static Config = Config;
81
- static EventSchemas = EventSchemas;
82
-
83
- public async run(obs: Observable) {
84
- // Traces automatically sent to Zipkin
85
- obs.log.info("Service started"); // Console log
86
-
87
- // Create child span
88
- const workObs = obs.span("heavy-work");
89
- workObs.setAttribute("work.type", "batch");
90
-
91
- try {
92
- await this.doWork();
93
- workObs.end();
94
- } catch (error) {
95
- workObs.recordException(error);
96
- workObs.end();
97
- }
98
- }
99
- }
68
+ this.log.info("Service started");
69
+ const workObs = this.obs.span("heavy-work");
70
+ await this.doWork();
71
+ workObs.end();
100
72
  ```
101
73
 
102
74
  ## Zipkin Setup
103
75
 
104
- Run Zipkin locally with Docker:
76
+ Run Zipkin locally:
105
77
 
106
78
  ```bash
107
79
  docker run -d -p 9411:9411 openzipkin/zipkin
108
80
  ```
109
81
 
110
- Access UI at: http://localhost:9411
82
+ ## Documentation
111
83
 
112
- ## Architecture
84
+ Detailed documentation (used by the BSB Registry): `https://github.com/BetterCorp/better-service-base/blob/master/plugins/nodejs/observable-zipkin/docs/plugin.md`
113
85
 
114
- ```
115
- BSB Application
116
- ↓
117
- Observable (DTrace)
118
- ↓
119
- observable-zipkin
120
- ↓
121
- OpenTelemetry SDK
122
- ↓
123
- Zipkin Exporter
124
- ↓
125
- Zipkin Server (HTTP)
126
- ```
86
+ ## Links
127
87
 
128
- ## Configuration Options
129
-
130
- | Option | Type | Default | Description |
131
- |--------|------|---------|-------------|
132
- | `serviceName` | string | `"bsb-service"` | Service identifier in Zipkin |
133
- | `serviceVersion` | string | - | Service version tag |
134
- | `zipkin.url` | string | `"http://localhost:9411/api/v2/spans"` | Zipkin API endpoint |
135
- | `zipkin.headers` | object | - | Custom HTTP headers |
136
- | `export.maxBatchSize` | number | `100` | Max spans per batch |
137
- | `export.maxQueueSize` | number | `2048` | Max queued spans |
138
- | `export.scheduledDelayMillis` | number | `5000` | Flush interval (ms) |
139
- | `samplingRate` | number | `1.0` | Sampling probability (0-1) |
140
- | `console.enabled` | boolean | `true` | Enable console logs |
141
- | `console.logLevel` | string | `"info"` | Minimum log level |
142
-
143
- ## Comparison with Other Observability Plugins
144
-
145
- | Plugin | Traces | Metrics | Logs | Backend |
146
- |--------|--------|---------|------|---------|
147
- | observable-zipkin | ✅ | ❌ | Console | Zipkin |
148
- | observable-opentelemetry | ✅ | ✅ | ✅ | OTLP Collector |
149
- | observable-default | ❌ | ❌ | Console | - |
88
+ - GitHub: `https://github.com/BetterCorp/better-service-base/tree/master/plugins/nodejs/observable-zipkin`
89
+ - BSB Registry (package): `https://io.bsbcode.dev/packages/nodejs/@bsb/observable-zipkin`
150
90
 
151
91
  ## License
152
92
 
153
- AGPL-3.0 - See LICENSE file for details.
154
-
155
- Commercial licenses available at https://www.bettercorp.dev
93
+ (AGPL-3.0-only OR Commercial)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsb/observable-zipkin",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Zipkin tracing integration for BSB framework",
5
5
  "main": "lib/plugins/observable-zipkin/index.js",
6
6
  "types": "lib/plugins/observable-zipkin/index.d.ts",
@@ -24,7 +24,7 @@
24
24
  "license": "(AGPL-3.0-only OR Commercial)",
25
25
  "author": {
26
26
  "name": "BetterCorp (PTY) Ltd",
27
- "email": "nick@bettercorp.dev",
27
+ "email": "ninja@bettercorp.dev",
28
28
  "url": "https://bettercorp.dev/"
29
29
  },
30
30
  "peerDependencies": {
@@ -44,6 +44,9 @@
44
44
  "rimraf": "^6.0.1",
45
45
  "typescript": "^5.7.3"
46
46
  },
47
- "homepage": "https://io.bsbcode.dev/plugins/bsb/observable-zipkin"
47
+ "homepage": "https://io.bsbcode.dev/packages/nodejs/@bsb/observable-zipkin"
48
48
  }
49
-
49
+
50
+
51
+
52
+