@ogcio/o11y-sdk-node
Version:
Opentelemetry standard instrumentation SDK for NodeJS based project
368 lines (278 loc) • 10.2 kB
Markdown
The NodeJS observability sdk is a npm package used to setup and implement opentelemetry instrumentation.
pnpm
```bash
pnpm i --save @ogcio/o11y-sdk-node
```
npm
```bash
npm i @ogcio/o11y-sdk-node
```
Setup using constructor function
```javascript
// instrumentation.ts
import("@ogcio/o11y-sdk-node/lib/index").then((sdk) =>
sdk.instrumentNode({
serviceName: "node-microservice",
collectorUrl: "http://localhost:4317",
resourceAttributes: {
"team.infra.cluster": "dev-01",
"team.infra.pod": "01",
"team.service.type": "fastify",
},
spanAttributes: {
"signal.namespace": "documentation",
},
ignoreUrls: [{ type: "equals", url: "/api/health" }],
}),
);
```
Run your node script with instrumentation
`node --import instrumentation.js server.js`
Or setup inside your package.json
```json
{
"main": "dist/index.js",
"type": "module",
"scripts": {
"start": "node --env-file=.env --import ./dist/instrumentation.js dist/index.js"
}
}
```
It is possible to customize spans such as traces and logs globally or in a single code statement using predefined functions.
In the SDK configuration, you can set the following properties:
- `spanAttributes` Object containing static properties or functions used to evaluate custom attributes for every logs and traces.
- `resourceAttributes` Object containing static properties used as resources attributes for any signal.
- `traceRatio` Faction value from 0 to 1, used by TraceIdRatioBasedSampler which it deterministically samples a percentage of traces that you pass in as a parameter.
```typescript
function generateRandomString(): string {
return Math.random() + "_" + Date.now();
}
instrumentNode({
resourceAttributes: {
"property.name.one": "value_one",
"property.name.two": "value_two",
},
spanAttributes: {
"custom.span.value": "example",
"custom.span.value_with_function": generateRandomString,
},
});
```
By default the sdk detect and redact email PII from traces and logs
example:
```
input: user access: name.lastname@domain.com
output: user access: [REDACTED EMAIL]
```
You can disable PII detection with `detection` object inside `NodeSDKConfig`
```typescript
instrumentNode({
detection: {
email: false,
},
});
```
By default the sdk detect and redact email PII from traces and logs
example:
```
input: user acces: name.lastname@domain.com
output: user access: [REDACTED EMAIL]
```
You can disable PII detection with `detection` object inside `NodeSDKConfig`
```typescript
instrumentNode({
detection: {
email: false,
},
});
```
-
- **Automatic Span Management**: Spans are automatically started, ended, and their status is set based on execution success or failure
- **Exception Recording**: Errors are automatically recorded with proper span status codes
- **Flexible Configuration**: Support for custom tracer names, span options, and attributes
- **Promise Support**: Works seamlessly with both synchronous and asynchronous functions
- **Nested Tracing**: Spans created within existing trace contexts automatically become child spans
```ts
import { SpanOptions } from "@opentelemetry/api";
export type WithSpanParams<T> = {
/**
* The name of the trace the span should belong to.
* NOTE: If you want the new span to belong to an already existing trace, you should provide the same tracer name
*/
traceName?: string;
spanName: string;
spanOptions?: SpanOptions;
/** A function defining the task you want to be wrapped by this span */
fn: (span: Span) => T | Promise<T>;
};
```
Use to create a top-level trace for background jobs, workers, or any standalone operations: `withSpan`
```ts
import { withSpan } from "@ogcio/o11y-sdk-node";
async function processEmailQueue() {
return withSpan({
traceName: "email-worker",
spanName: "process-email-queue",
fn: async (span) => {
// Your worker logic here
const emails = await fetchPendingEmails();
span.setAttributes({
"email.count": emails.length,
"worker.batch.id": generateBatchId(),
});
for (const email of emails) {
await sendEmail(email);
}
return { processed: emails.length };
},
});
}
```
Create child spans within existing trace contexts to provide detailed operation breakdown:
```typescript
async function orderProcessing(orderId: string) {
return withSpan({
spanName: "process-order",
fn: async (parentSpan) => {
// Child span for validation
const validation = await withSpan({
spanName: "validate-order",
fn: async (span) => {
span.setAttribute("order.id", orderId);
return await validateOrder(orderId);
},
});
// Child span for payment
const payment = await withSpan({
spanName: "process-payment",
fn: async (span) => {
span.setAttribute("payment.amount", validation.amount);
return await processPayment(orderId, validation.amount);
},
});
parentSpan.setAttributes({
"order.status": "completed",
"order.total": payment.amount,
});
return { orderId, status: "completed" };
},
});
}
```
-
Using `getActiveSpan` function, you can access to current transaction span and customize it.
You can use the function everywhere in your code, and set some custom attributes that are enabled for that single span
```typescript
import { getActiveSpan } from "@ogcio/o11y-sdk-node";
async function routes(app: FastifyInstance) {
app.get("/", async (req, reply) => {
// validation and business logic
// set span attribute
getActiveSpan()?.setAttribute("business.info", "dummy");
reply.status(200).send(response);
});
}
```
This package gives the possibility to send custom metrics and define them as desired in the code, you can choose between sync metrics and observable async metrics.
To use this functionality, you only need to import `getMetric` and enable the application instrumentation.
```typescript
import { getMetric } from "@ogcio/o11y-sdk-node";
```
Sync metrics are signals sent when the function has been called.
Creating a counter, there are 2 types of counter:
- **counter** a simple counter that can only add positive numbers
- **updowncounter** counter that support also negative numbers
```typescript
const counter = getMetric("counter", {
attributeName: "counter",
metricName: "fastify-counter",
});
counter.add(1, {
my: "my",
custom: "custom",
attributes: "attributes",
});
```
Creating a Histogram
```typescript
const histogram = getMetric("histogram", {
metricName: "response_duration",
attributeName: "http_response",
options: {
advice: {
explicitBucketBoundaries: [0, 100, 200, 500, 1000],
},
description: "Response durations",
},
});
histogram.record(120, { path: "/home" });
```
Async metrics are called by the scraper collector to read current data using the `Observable` pattern.
Creating an async metric means that the application will subscribe to the observability URL and record data on call (default 60s).
_keep in mind, you can't send signals on-demand with this component_
Creating an async Gauge
```typescript
const asyncGauge = getMetric("async-gauge", {
metricName: "cpu_usage",
attributeName: "server_load",
options: { unit: "percentage" },
}).addCallback((observer) => {
observer.observe(50, { host: "server1" });
});
```
Creating an async Counter
```typescript
getMetric("async-counter", {
attributeName: "scraped-memory",
metricName: "fastify-counter",
}).addCallback((observer) => {
observer.observe(freemem(), {
"application.os.memory": "free-memory",
});
});
```
protocol is a string parameter used to define how to send signals to observability infrastructure
- **grpc** Use gRPC protocol, usually default port use 4317. Is the most performant option for server side applications.
- **http** Use HTTP standard protocol, usually default port use 4318. Mainly used on web or UI client applications.
- **console** Used for debugging sending signals to observability cluster, every information will be printed to your runtime console.
```typescript
export type SDKLogLevel =
| "NONE"
| "ERROR"
| "WARN"
| "INFO"
| "DEBUG"
| "VERBOSE"
| "ALL";
```
| Parameter | Type | Description |
| :-------------- | :---------------- | :------------------------------------------------------------------------------------------------------- |
| `collectorUrl` | `string` | **Required**. The opentelemetry collector entrypoint url, if null, instrumentation will not be activated |
| `serviceName` | `string` | Name of your application used for the collector to group logs |
| `diagLogLevel` | `SDKLogLevel` | Diagnostic log level for the internal runtime instrumentation |
| `collectorMode` | `single \| batch` | Signals sending mode, default is batch for performance |
| `enableFS` | `boolean` | Flag to enable or disable the tracing for node:fs module |
| `protocol` | `string` | Type of the protocol used to send signals |