OpenTelemetry Viem Instrumentation for Node.js

This module provides automatic opentelemetry instrumentation for the viem 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

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

Supported Versions

• viem versions >2.8.18

Usage

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:

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 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 |