How to Add JSON-RPC Protocol Support

[4406arthur]

How to Add JSON-RPC Protocol Support

Hi everyone! I'm working on extending Beyla's capabilities to support JSON-RPC protocol monitoring by adding custom metrics. Specifically, I want to add a new metric called jsonrpc.method,jsonrpc.server.duration, jsonrpc.response.status_code to track JSON-RPC calls.

Current Situation

Currently, Beyla supports automatic instrumentation for various protocols, including HTTP/gRPC. However, for JSON-RPC support, we need to handle HTTP payload parsing differently since JSON-RPC has its own specific message format(URI is not useful).

{
    "jsonrpc": "2.0",
    "method": "methodName",
    "params": [...],
    "id": 1
}

need some guideline to how to extend Beyla project

it not quit easy to know the pipeline
like how to inject http payload into eBPF map
and became a metrics or OTEL format

[marctc]

Hey @4406arthur, thanks a lot for your interest in Beyla and will to contribute. Indeed touching Beyla is not easy and it could be intimidating in the beginning. What you want to do it's not straightforward, but not crazy to implement. I can give you some steps to provide some guidance, but you would need to do some research by your own.

If you want to add generic suport for JSON-RPC, you have to know how the protocol works. In pkg/internal/ebpf/common/tcp_detect_transform.go any TCP packet captured from BPF passes through the ReadTCPRequestIntoSpan function, and depending what's in the bytes, you can identify if the packet is sql, redis, kafka or grpc.

So basically you will need to see if there's any easy way to identify JSON-RPC packets from other packets. Once you have that, you need to know where in the packets the rest information is. In cases like SQL is easy, because it's just plain text. But if it's a binary protocol it gets more complicated as you need to understand when the frames start and end in the sequence of bytes.

Once you have this done (the hard part!) you have to create a new EventType in pkg/internal/request/span.go. Look how other EventTypes are handled, and you probably need to edit every single file where the data is flowing. For example, to add a new OTEL trace you have to edit traceAttributes in pkg/export/otel/traces.go.

Also, is always good to check if there's already semantic conventions defined in OpenTelemetry spec for those attributes.

I hope this explanation it helps. I you need clarification, let us know or reach us in our community slack.

[4406arthur]

Thank you @marctc for such a well-structured explanation!
I'll start by researching JSON-RPC packet structures and will follow your suggested path through the codebase.

[grcevski]

Great idea @4406arthur, I would start perhaps by adding a test example in our test/integration/components and then as Marc suggested, we can add JSON-RPC detector like we've done for other programs in tcp_detect_transform.go.

[4406arthur]

that would be helpful, lots of blockchain service leverage JSON-RPC

[marctc]

Added docs explaining this: #1618