@pimlico/opentelemetry-instrumentation-viem NPM

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)