Add support for NATS protocol by marctc · Pull Request #1712 · open-telemetry/opentelemetry-ebpf-instrumentation

marctc · 2026-04-02T10:06:47Z

Summary

Add support to capture span from clients using NATS protocol.

Validation

I have read and followed the contributing guidelines
If this enhances / fixes / changes a core feature, I have updated the features documentation

codecov · 2026-04-02T10:13:26Z

Codecov Report

❌ Patch coverage is 78.72861% with 87 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.13%. Comparing base (d5c3c0b) to head (59c311f).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/ebpf/common/nats_detect_transform.go	73.01%	56 Missing and 22 partials ⚠️
pkg/ebpf/common/common.go	77.77%	4 Missing and 2 partials ⚠️
pkg/ebpf/common/tcp_detect_transform.go	85.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1712      +/-   ##
==========================================
- Coverage   78.14%   78.13%   -0.01%     
==========================================
  Files         278      279       +1     
  Lines       34240    34620     +380     
==========================================
+ Hits        26758    27052     +294     
- Misses       6229     6293      +64     
- Partials     1253     1275      +22

Flag	Coverage Δ
integration-test	`55.09% <15.15%> (-0.50%)`	⬇️
integration-test-arm	`28.61% <12.71%> (-0.12%)`	⬇️
integration-test-vm-x86_64-5.15.152	`28.62% <10.75%> (-0.56%)`	⬇️
integration-test-vm-x86_64-6.10.6	`29.22% <12.22%> (+0.14%)`	⬆️
k8s-integration-test	`41.25% <10.75%> (-0.91%)`	⬇️
oats-test	`37.26% <44.98%> (-0.36%)`	⬇️
unittests	`58.55% <77.99%> (+0.21%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

grcevski

I just had a few minor comments, but this is looking pretty good!

grcevski · 2026-04-02T13:44:20Z

+		return errors.New("invalid NATS sid")
+	}
+	for _, b := range field {
+		if (b < '0' || b > '9') && (b < 'a' || b > 'z') && (b < 'A' || b > 'Z') {


sql_detect_transform has the same code, maybe we can combine this into a common helper?

grcevski · 2026-04-02T13:49:02Z

+
+		return natsFrame{clientID: meta.Name, valid: true}, nil
+	case "SUB":
+		if len(fields) != 3 && len(fields) != 4 {


Nit: I found these statements confusing with != 3 && !=4. It might be better to write them as !(len==3 || len==4)

this is how it was before, but linter is not happy:

Error: pkg/ebpf/common/nats_detect_transform.go:139:6: QF1001: could apply De Morgan's law (staticcheck) if !(len(fields) == 3 || len(fields) == 4) {

ah ok, cool!

grcevski · 2026-04-02T13:54:56Z

+	)))
+}
+
+func TestParseNATSFrame(t *testing.T) {


Can we add more tests with all the variations of !=4 && !=5?

Copilot

Pull request overview

This PR adds end-to-end support for capturing NATS (plain TCP) messaging spans, including protocol detection/parsing in the eBPF TCP pipeline, wiring NATS into instrumentation selection/config/schema, and exporting NATS spans/metrics via Prometheus and OTEL (plus an OATS integration suite).

Changes:

Add NATS protocol parsing/detection in the TCP userspace parser and map it to new NATS span event types.
Export NATS spans/attributes and messaging publish/process duration metrics in both Prometheus and OTEL exporters.
Add documentation + config schema updates + an OATS NATS integration test suite (Python client).

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/obi/config.go	Enable NATS in default instrumentation list.
pkg/obi/config_test.go	Update config tests to include NATS defaults.
pkg/export/prom/prom.go	Record messaging publish/process histograms for NATS spans.
pkg/export/prom/prom_test.go	Add Prom metrics expectations and span fixtures for NATS.
pkg/export/otel/tracesgen/tracesgen.go	Gate NATS spans on instrumentation selection; emit NATS messaging attributes; set span kinds.
pkg/export/otel/traces_test.go	Add NATS trace attribute test vectors and instrumentation filtering expectations.
pkg/export/otel/metrics.go	Record OTEL messaging publish/process metrics for NATS spans.
pkg/export/otel/metrics_test.go	Add NATS metric expectations and connection-type coverage.
pkg/export/otel/metrics_svc_graph_test.go	Include NATS in service graph connection type validation.
pkg/export/instrumentations/instr_options.go	Add `InstrumentationNATS`, selection flag, and NATSEnabled/MQEnabled logic.
pkg/export/instrumentations/instr_options_test.go	Add selection tests for NATSEnabled and MQEnabled behavior.
pkg/ebpf/common/tcp_detect_transform.go	Detect NATS traffic, parse it, and emit main + optional extra span.
pkg/ebpf/common/tcp_detect_transform_test.go	Add NATS parsing tests and coalesced publish+process extra-span emission test.
pkg/ebpf/common/nats_detect_transform.go	New NATS protocol parser, heuristic detection, and span conversion.
pkg/ebpf/common/nats_detect_transform_test.go	Unit tests for NATS heuristics, frame parsing, and event handling.
pkg/ebpf/common/common.go	Add protocol type placeholder and mark NATS client spans as client events.
pkg/appolly/app/request/span.go	Add NATS event types and integrate into span kind, naming, attrs, and service graph connection type.
pkg/appolly/app/request/span_test.go	Extend span tests for new NATS event types and behaviors.
pkg/appolly/app/request/span_getters.go	Add OTEL getter support for NATS messaging attributes.
pkg/appolly/app/request/span_getters_test.go	Add getter test coverage for NATS messaging attributes.
Makefile	Add `oats-test-nats` and include it in `oats-test`.
internal/test/oats/nats/yaml/oats_python_nats.yaml	OATS spec validating NATS spans + messaging duration metrics.
internal/test/oats/nats/oats_test.go	Register NATS OATS suite.
internal/test/oats/nats/go.mod	Go module for the NATS OATS suite.
internal/test/oats/nats/go.sum	Dependency lockfile for the NATS OATS suite.
internal/test/oats/nats/docker-compose-obi-python-nats.yml	Compose stack: NATS server + python test app + instrumenter.
internal/test/oats/nats/docker-compose-include-base.yml	Template include helper for OATS compose generation.
internal/test/oats/nats/docker-compose-generic-template.yml	Generic OATS infra stack template (grafana/prom/tempo/collector).
internal/test/oats/nats/configs/tempo-config.yaml	Tempo config for OATS NATS suite.
internal/test/oats/nats/configs/prometheus-config.yml	Prometheus config for OATS NATS suite.
internal/test/oats/nats/configs/otelcol-config.yaml	Collector pipeline for traces/metrics in OATS NATS suite.
internal/test/oats/nats/configs/instrumenter-config-traces.yml	Instrumenter routes config used by the suite.
internal/test/oats/nats/configs/grafana-datasources.yaml	Grafana datasources for the suite stack.
internal/test/integration/components/pythonnats/requirements.txt	Pinned python dependency (nats-py) for integration component.
internal/test/integration/components/pythonnats/requirements.in	Input dependency list for pip-compile.
internal/test/integration/components/pythonnats/main.py	Python app that publishes to NATS and serves a `/publish` endpoint.
internal/test/integration/components/pythonnats/Dockerfile	Container image for the python NATS test component.
docs/config-schema.json	Add `nats` to instrumentation enums in the config schema.
devdocs/protocols/tcp/README.md	Link NATS protocol parser documentation.
devdocs/protocols/tcp/nats.md	New documentation for the NATS TCP parser and limitations.
devdocs/features.md	Document NATS support in features matrix.

grcevski

LGTM!

Copilot

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated no new comments.

rafaelroquetto

Overall, I think we should do another pass to split the code for clarity, and also ensure no unecessary string allocations are taking place (that's one of the reasons why I refactored the sql code when doing the large buffers API, so I would prefer if we did not drift from the approach).

It might be worth it doing a local review telling your agent to look into AGENTS.md - for some reason I think copilot (the github one) has been sloppy and missing a lot of obvious cases.

github-actions · 2026-04-22T10:37:06Z

CI Supervisor

Workflow	Job	Last state	Re-running?	Attempt
PR OATS test	nats	failure	No	2/2
Pull request checks	Generate and checks	failure	No	2/2
Pull request integration tests	shard-5 (11 tests)	failure	No	2/2

marctc force-pushed the add-nats branch 2 times, most recently from 1f87cbe to e86822a Compare April 2, 2026 13:44

grcevski reviewed Apr 2, 2026

View reviewed changes

marctc marked this pull request as ready for review April 2, 2026 13:57

marctc requested a review from a team as a code owner April 2, 2026 13:57

marctc requested a review from Copilot April 2, 2026 14:07

Copilot started reviewing on behalf of marctc April 2, 2026 14:07 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Comment thread pkg/ebpf/common/nats_detect_transform.go

Comment thread pkg/ebpf/common/tcp_detect_transform.go Outdated

Comment thread pkg/ebpf/common/nats_detect_transform.go Outdated

grcevski approved these changes Apr 2, 2026

View reviewed changes

rafaelroquetto requested a review from Copilot April 2, 2026 15:32

Copilot started reviewing on behalf of rafaelroquetto April 2, 2026 15:33 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

rafaelroquetto requested changes Apr 2, 2026

View reviewed changes

marctc added 6 commits April 22, 2026 10:29

Add support for NATS protocol

38a615b

pr feedback

d271245

pr feedback

6dcbc87

fix linter

3649b6e

Align semantic conventions

11921d2

PR feedback

593d220

marctc force-pushed the add-nats branch from dd4185d to 593d220 Compare April 22, 2026 10:33

marctc added 3 commits April 22, 2026 12:39

refactor ascii

0bb370c

remove dead code

3737791

fix ci

992ae34

marctc requested a review from rafaelroquetto April 22, 2026 14:26

marctc added 3 commits April 22, 2026 16:29

run go mod tidy in oat test

71cd5ef

Merge remote-tracking branch 'upstream/main' into add-nats

fe647f4

Update config schema/docs for NATS instrumentation

59c311f

Conversation

marctc commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

codecov Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

grcevski left a comment

Choose a reason for hiding this comment

Uh oh!

grcevski Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

grcevski Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

marctc Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

grcevski Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

grcevski Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

grcevski left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

rafaelroquetto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Supervisor

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

marctc commented Apr 2, 2026 •

edited

Loading

codecov Bot commented Apr 2, 2026 •

edited

Loading

github-actions Bot commented Apr 22, 2026 •

edited

Loading