npm package: @pimlico/opentelemetry-instrumentation-viem
Description: OpenTelemetry instrumentation for viem library
Author: Pimlico
Latest version: 0.0.5-alpha.1

# OpenTelemetry Viem Instrumentation for Node.js

This module provides automatic opentelemetry instrumentation for the [viem](https://viem.sh/) library. It patches the low-level JSON-RPC client in viem to create spans for each RPC request, providing detailed visibility into Ethereum interactions. Key features include:

- Automatic tracing of all JSON-RPC requests made through viem
- Detailed span attributes following OpenTelemetry RPC conventions
- Support for batch requests
- Configurable parent span requirement for controlled propagation
- Custom attribute hooks for extending span information
- Error capturing with detailed error information

## Installation

```bash
npm install --save @pimlico/opentelemetry-instrumentation-viem
```

### Supported Versions

- viem versions `>2.8.18`

## Usage

```ts
import { NodeSDK } from "@opentelemetry/sdk-node"
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
import { ViemInstrumentation } from "@pimlico/opentelemetry-instrumentation-viem"

const sdk = new NodeSDK({
    traceExporter: new ConsoleSpanExporter(),
    instrumentations: [
        new ViemInstrumentation({
            requireParentSpan: true,
            captureOperationResult: true
        })
    ],
})

sdk.start()
```

### Viem Instrumentation Options

Viem instrumentation has a few options available to customize the behavior:

| Option | Type | Description | Default |
| --- | --- | --- | --- |
| `requestHook` | `RequestHook` | Hook for adding custom attributes to spans created by the instrumentation | `undefined` |
| `requireParentSpan` | `boolean` | Whether to require a parent span to be present for creating spans | `false` |
| `captureOperationResult` | `boolean` | Whether to capture operation result information. When enabled, adds basic type information about the response. | `false` |

#### Using the Request Hook

The request hook allows you to add custom attributes to spans based on the request parameters:

```js
const { ViemInstrumentation } = require('@pimlico/opentelemetry-instrumentation-viem');

const viemInstrumentation = new ViemInstrumentation({
  requestHook: (span, request) => {
    // Add custom attributes based on the request
    span.setAttribute('custom.attribute', 'custom value');

    // You can also access request parameters
    if (request.body.method === 'eth_getBalance') {
      span.setAttribute('account.address', request.body.params[0]);
    }
  }
});
```

## Metrics

This instrumentation does not provide any metrics.

## Trace Semantic Conventions

This instrumentation follows the [OpenTelemetry RPC conventions](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/) for spans and adds the following attributes:

| Attribute Name | Type | Description |
| --- | --- | --- |
| `rpc.system` | string | Always set to `jsonrpc` |
| `rpc.service` | string | Always set to `evm-jsonrpc` |
| `rpc.method` | string | The JSON-RPC method name (e.g., `eth_getBalance`, `eth_call`) |
| `rpc.jsonrpc.version` | string | Always set to `2.0` |
| `rpc.jsonrpc.request_id` | string | The JSON-RPC request ID |
| `server.address` | string | The hostname of the JSON-RPC server |
| `server.port` | string | The port of the JSON-RPC server |
| `url.full` | string | The full URL of the JSON-RPC server |
| `url.path` | string | The path component of the URL |
| `url.scheme` | string | The scheme component of the URL (http or https) |

When `captureOperationResult` is enabled and an error occurs, the following additional attributes are added:

| Attribute Name | Type | Description |
| --- | --- | --- |
| `rpc.jsonrpc.error_code` | number | The JSON-RPC error code |
| `rpc.jsonrpc.error_message` | string | The JSON-RPC error message |