@yashshukla/observeiq-node 0.1.0 → 0.1.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 +164 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# @yashshukla/observeiq-node
|
|
2
|
+
|
|
3
|
+
Distributed tracing SDK for Node.js. Drop it into any service to trace requests end-to-end and send spans to an ObserveIQ collector.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @yashshukla/observeiq-node
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { Tracer } from '@yashshukla/observeiq-node';
|
|
19
|
+
|
|
20
|
+
const tracer = new Tracer({
|
|
21
|
+
serviceName: 'order-service',
|
|
22
|
+
collectorUrl: 'http://localhost:4318/ingest',
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
await tracer.trace('createOrder', async () => {
|
|
26
|
+
// your logic here
|
|
27
|
+
await db.insert(order);
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Nested calls are automatically linked as parent/child spans:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
await tracer.trace('handleRequest', async () => {
|
|
35
|
+
await tracer.trace('validateUser', async () => { ... });
|
|
36
|
+
await tracer.trace('fetchCart', async () => { ... });
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## How it works
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
Your Service
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
tracer.trace() ← wraps your function, records start/end time
|
|
49
|
+
│
|
|
50
|
+
│ AsyncLocalStorage propagates traceId + spanId across async calls
|
|
51
|
+
▼
|
|
52
|
+
POST /ingest ← HTTP POST to collector with the Span payload
|
|
53
|
+
│
|
|
54
|
+
▼
|
|
55
|
+
RabbitMQ ← collector pushes span onto queue
|
|
56
|
+
│
|
|
57
|
+
▼
|
|
58
|
+
Worker ← reads queue, inserts into PostgreSQL
|
|
59
|
+
│
|
|
60
|
+
▼
|
|
61
|
+
Dashboard ← waterfall chart built from span tree
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Span shape
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
interface Span {
|
|
70
|
+
traceId: string;
|
|
71
|
+
spanId: string;
|
|
72
|
+
parentSpanId: string | null;
|
|
73
|
+
operationName: string;
|
|
74
|
+
serviceName: string;
|
|
75
|
+
startTime: number; // Unix ms
|
|
76
|
+
duration: number; // ms
|
|
77
|
+
status: 'ok' | 'error';
|
|
78
|
+
tags: Record<string, string | number | boolean>;
|
|
79
|
+
error?: string;
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Configuration
|
|
86
|
+
|
|
87
|
+
| Option | Type | Required | Description |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| `serviceName` | `string` | Yes | Name of the service emitting spans |
|
|
90
|
+
| `collectorUrl` | `string` | Yes | Full URL of the collector ingest endpoint |
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Requirements
|
|
95
|
+
|
|
96
|
+
- Node.js 18+
|
|
97
|
+
- An ObserveIQ collector running and reachable at `collectorUrl`
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Architecture
|
|
102
|
+
|
|
103
|
+
See the full platform: [github.com/yash-shukla-git/observeiq](https://github.com/yash-shukla-git/observeiq)
|
|
104
|
+
|
|
105
|
+
The monorepo contains:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
observeiq/
|
|
109
|
+
├── apps/
|
|
110
|
+
│ ├── collector/ Express server — receives spans, pushes to RabbitMQ
|
|
111
|
+
│ ├── worker/ Reads queue, writes to PostgreSQL
|
|
112
|
+
│ └── dashboard/ Waterfall UI (Week 2)
|
|
113
|
+
├── packages/
|
|
114
|
+
│ └── sdk/ This package
|
|
115
|
+
└── docker-compose.yml PostgreSQL + RabbitMQ
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Contributing
|
|
121
|
+
|
|
122
|
+
1. Clone the repo
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
git clone https://github.com/yash-shukla-git/observeiq.git
|
|
126
|
+
cd observeiq
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
2. Install dependencies
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
npm install
|
|
133
|
+
cd packages/sdk && npm install
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
3. Start infrastructure
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
docker compose up -d
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
4. Build the SDK
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
cd packages/sdk
|
|
146
|
+
npm run build
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
5. Run the mock emitter to test the full pipeline
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
cd scripts
|
|
153
|
+
ts-node mock-emitter.ts
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
6. Make your changes in `packages/sdk/src/`, rebuild, and verify spans appear in PostgreSQL.
|
|
157
|
+
|
|
158
|
+
Open a PR against `main`. Keep changes focused — one concern per PR.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## License
|
|
163
|
+
|
|
164
|
+
MIT
|
package/package.json
CHANGED