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