@faststore/diagnostics 4.1.0 → 4.1.1-dev.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 +98 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,98 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://faststore.dev">
|
|
3
|
+
<img alt="Faststore" src="../ui/static/logo.png" width="60" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
<h1 align="center">
|
|
7
|
+
Faststore Diagnostics
|
|
8
|
+
</h1>
|
|
9
|
+
<p align="center">
|
|
10
|
+
<strong>
|
|
11
|
+
OpenTelemetry tracing and telemetry for FastStore
|
|
12
|
+
</strong>
|
|
13
|
+
</p>
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href="https://www.npmjs.com/package/@faststore/diagnostics">
|
|
16
|
+
<img src="https://badge.fury.io/js/%40faststore%2Fdiagnostics.svg" alt="npm version" />
|
|
17
|
+
</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
`@faststore/diagnostics` initializes OpenTelemetry tracing, logging, and metrics for FastStore server-side instrumentation. It is a thin wrapper around `@vtex/diagnostics-nodejs` and is consumed by `@faststore/core` via Next.js instrumentation when telemetry is enabled.
|
|
21
|
+
|
|
22
|
+
## Package structure
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
src/
|
|
26
|
+
├── globals.ts # Initializes the global fsDiagnostics state (telemetry client map, IS_DEV flag)
|
|
27
|
+
├── start.ts # getTelemetryClient() and getTraceClient() implementations
|
|
28
|
+
└── index.ts # Public exports
|
|
29
|
+
configs/
|
|
30
|
+
├── dev.json # Telemetry client config for development
|
|
31
|
+
└── prod.json # Telemetry client config for production
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## How it works
|
|
35
|
+
|
|
36
|
+
`@faststore/core` calls `getTelemetryClient()` at server startup via Next.js `instrumentation.ts`:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
// packages/core/src/instrumentation.ts
|
|
40
|
+
import { getTelemetryClient } from '@faststore/diagnostics'
|
|
41
|
+
|
|
42
|
+
await getTelemetryClient({
|
|
43
|
+
serviceName: config.analytics?.serviceName ?? name,
|
|
44
|
+
version,
|
|
45
|
+
account: config.api.storeId,
|
|
46
|
+
clientName: config.api.storeId,
|
|
47
|
+
packageName: name,
|
|
48
|
+
})
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
This initializes traces, logs, and metrics clients and registers HTTP instrumentation. Telemetry data is exported to an OTLP endpoint.
|
|
52
|
+
|
|
53
|
+
## Configuration
|
|
54
|
+
|
|
55
|
+
| Variable | Default | Description |
|
|
56
|
+
| :--- | :--- | :--- |
|
|
57
|
+
| `OTLP_TRACES_ENDPOINT` | `localhost:4317` | OTLP gRPC endpoint for trace export |
|
|
58
|
+
| `NODE_ENV` | — | `production` disables dev mode and uses `configs/prod.json` |
|
|
59
|
+
|
|
60
|
+
To enable telemetry in a store, set `analytics.otelEnabled: true` in `discovery.config.js`.
|
|
61
|
+
|
|
62
|
+
## How to develop
|
|
63
|
+
|
|
64
|
+
All logic lives in `src/start.ts` and `src/globals.ts`. To make changes:
|
|
65
|
+
|
|
66
|
+
1. Edit the relevant file in `src/`
|
|
67
|
+
2. Run `pnpm build` to compile
|
|
68
|
+
3. Verify via `@faststore/core` — since it's a workspace dependency, `instrumentation.ts` picks up your local build automatically
|
|
69
|
+
|
|
70
|
+
> Changes are validated by running `@faststore/core` with `analytics.otelEnabled: true` and checking that traces reach the configured OTLP endpoint.
|
|
71
|
+
|
|
72
|
+
## How to run
|
|
73
|
+
|
|
74
|
+
### Prerequisites
|
|
75
|
+
|
|
76
|
+
- Node.js ≥ 20
|
|
77
|
+
- pnpm
|
|
78
|
+
|
|
79
|
+
### Local setup
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
# 1. Install dependencies (from the repo root)
|
|
83
|
+
pnpm install
|
|
84
|
+
|
|
85
|
+
# 2. Build the package
|
|
86
|
+
pnpm build
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## How to publish
|
|
90
|
+
|
|
91
|
+
Versioning and publishing are managed at the monorepo root by Lerna. Do not publish this package independently. Refer to the [Contributing guidelines](../../CONTRIBUTING.MD) for the full release workflow.
|
|
92
|
+
|
|
93
|
+
## Documentation
|
|
94
|
+
|
|
95
|
+
- **Sampling config (dev):** [`configs/dev.json`](./configs/dev.json) — 100% sample rate
|
|
96
|
+
- **Sampling config (prod):** [`configs/prod.json`](./configs/prod.json) — 1% default, 30% for `trace_all`
|
|
97
|
+
- **Upstream library:** [@vtex/diagnostics-nodejs](https://www.npmjs.com/package/@vtex/diagnostics-nodejs)
|
|
98
|
+
- **OpenTelemetry:** [opentelemetry.io](https://opentelemetry.io)
|