Merge pull request #98 from ajimenez1503/feat/grpc-receiver-support

gRPC OTel Receiver support

Author: krisztianfekete

Dockerfile

@@ -33,6 +33,6 @@ USER app
 ENV PATH="/app/.venv/bin:$PATH"
 ENV AGENTEVALS_SERVER_URL=http://127.0.0.1:8001
 
-EXPOSE 8001 4318 8080
+EXPOSE 8001 4318 4317 8080
 
-CMD ["agentevals", "serve", "--host", "0.0.0.0", "--port", "8001", "--otlp-port", "4318", "--mcp-port", "8080"]
+CMD ["agentevals", "serve", "--host", "0.0.0.0", "--port", "8001", "--otlp-http-port", "4318", "--otlp-grpc-port", "4317", "--mcp-port", "8080"]

README.md

@@ -140,7 +140,14 @@ export OTEL_RESOURCE_ATTRIBUTES="agentevals.session_name=my-agent"
 python your_agent.py
 ```
 
-Traces stream to the UI in real-time. Works with LangChain, Strands, Google ADK, OpenAI Agents SDK, or any framework that emits OTel spans (`http/protobuf` and `http/json` supported). Sessions are auto-created and grouped by `agentevals.session_name`. Set `agentevals.eval_set_id` to associate traces with an eval set.
+For OTLP/gRPC exporters, use:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
+export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+```
+
+Traces stream to the UI in real-time. Works with LangChain, Strands, Google ADK, OpenAI Agents SDK, or any framework that emits OTel spans (`http/protobuf`, `http/json`, and OTLP/gRPC supported). Sessions are auto-created and grouped by `agentevals.session_name`. Set `agentevals.eval_set_id` to associate traces with an eval set.
 
 See [examples/zero-code-examples/](examples/zero-code-examples/) for working examples.
 

charts/agentevals/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: agentevals
-description: agentevals web UI, OTLP HTTP receiver, and MCP (Streamable HTTP)
+description: agentevals web UI, OTLP HTTP+gRPC receivers, and MCP (Streamable HTTP)
 type: application
 version: 0.1.0
 appVersion: "0.5.2"

charts/agentevals/templates/NOTES.txt

@@ -1,8 +1,9 @@
 1. UI and API are available at port {{ .Values.service.http.port }} (Service port name: http).
 2. OTLP HTTP receiver: port {{ .Values.service.otlpHttp.port }} (OTEL_EXPORTER_OTLP_ENDPOINT=http://<service>:{{ .Values.service.otlpHttp.port }}).
-3. MCP (Streamable HTTP): port {{ .Values.service.mcp.port }}, path /mcp (e.g. http://<service>:{{ .Values.service.mcp.port }}/mcp).
+3. OTLP gRPC receiver: port {{ .Values.service.otlpGrpc.port }} (OTEL_EXPORTER_OTLP_ENDPOINT=<service>:{{ .Values.service.otlpGrpc.port }}, OTEL_EXPORTER_OTLP_PROTOCOL=grpc).
+4. MCP (Streamable HTTP): port {{ .Values.service.mcp.port }}, path /mcp (e.g. http://<service>:{{ .Values.service.mcp.port }}/mcp).
 {{- if .Values.ephemeralVolume.enabled }}
-4. An emptyDir is mounted at /tmp with HOME=/tmp/agentevals-home (ephemeral; lost on pod restart). Set ephemeralVolume.enabled=false and readOnlyRootFilesystem=false if you need a writable root without this mount.
+5. An emptyDir is mounted at /tmp with HOME=/tmp/agentevals-home (ephemeral; lost on pod restart). Set ephemeralVolume.enabled=false and readOnlyRootFilesystem=false if you need a writable root without this mount.
 {{- end }}
 
 Get the Service URL:

charts/agentevals/templates/deployment.yaml

@@ -79,6 +79,9 @@ spec:
             - name: otlp-http
               containerPort: {{ .Values.service.otlpHttp.containerPort }}
               protocol: TCP
+            - name: otlp-grpc
+              containerPort: {{ .Values.service.otlpGrpc.containerPort }}
+              protocol: TCP
             - name: mcp
               containerPort: {{ .Values.service.mcp.containerPort }}
               protocol: TCP

charts/agentevals/templates/service.yaml

@@ -16,6 +16,10 @@ spec:
       port: {{ .Values.service.otlpHttp.port }}
       targetPort: otlp-http
       protocol: TCP
+    - name: otlp-grpc
+      port: {{ .Values.service.otlpGrpc.port }}
+      targetPort: otlp-grpc
+      protocol: TCP
     - name: mcp
       port: {{ .Values.service.mcp.port }}
       targetPort: mcp

charts/agentevals/values.yaml

@@ -111,6 +111,10 @@ service:
   otlpHttp:
     port: 4318
     containerPort: 4318
+  # -- OTLP gRPC receiver port
+  otlpGrpc:
+    port: 4317
+    containerPort: 4317
   # -- MCP (Streamable HTTP) port
   mcp:
     port: 8080

docs/otel-compatibility.md

@@ -80,11 +80,18 @@ If you maintain an OTel-instrumented agent framework and want to align with the
 
 ## OTLP Receiver
 
-agentevals runs an OTLP HTTP receiver on port 4318 (the standard OTLP HTTP port) that accepts:
+agentevals runs:
+
+- OTLP HTTP receiver on port 4318 (standard OTLP HTTP port)
+- OTLP gRPC receiver on port 4317 (standard OTLP gRPC port).
+
+OTLP HTTP accepts:
 
 | Endpoint | Content Types |
 |----------|--------------|
 | `/v1/traces` | `application/json`, `application/x-protobuf` |
 | `/v1/logs` | `application/json`, `application/x-protobuf` |
 
-Point your standard OTel exporters at `http://localhost:4318` and traces will stream into agentevals automatically. See [examples/README.md](../examples/README.md) for zero-code setup instructions.
+Point OTLP/HTTP exporters at `http://localhost:4318`.
+Point OTLP/gRPC exporters at `localhost:4317` with `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`.
+Traces and logs stream into agentevals automatically. See [examples/README.md](../examples/README.md) for zero-code setup instructions.

examples/README.md

@@ -14,7 +14,14 @@ export OTEL_RESOURCE_ATTRIBUTES="agentevals.session_name=my-agent,agentevals.eva
 python your_agent.py
 ```
 
-The OTLP receiver runs on port 4318 (standard OTLP HTTP port) and accepts both `http/protobuf` and `http/json`. Sessions are auto-created from incoming traces and grouped by `agentevals.session_name`.
+For OTLP/gRPC exporters, use:
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
+export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+```
+
+agentevals accepts OTLP/HTTP on port 4318 (`http/protobuf` and `http/json`) and OTLP/gRPC on port 4317. Sessions are auto-created from incoming traces and grouped by `agentevals.session_name`.
 
 | Example | Framework | LLM Provider |
 |---------|-----------|-------------|
@@ -108,7 +115,7 @@ The zero-code and SDK examples implement the same toy agent (dice rolling + prim
 
 | Example | Description |
 |---------|-------------|
-| [kubernetes/](./kubernetes/) | Deploy agentevals with kagent on Kubernetes, using an OTel Collector as a gRPC to HTTP bridge. Includes a walkthrough for comparing two kagent agents (different models) and evaluating them with tool trajectory and response match scores. |
+| [kubernetes/](./kubernetes/) | Deploy agentevals with kagent on Kubernetes using native OTLP gRPC ingestion (or optionally an OTel Collector). Includes a walkthrough for comparing two kagent agents (different models) and evaluating them with tool trajectory and response match scores. |
 
 ## Advanced: GenAI Semantic Convention Patterns
 

examples/kubernetes/README.md

@@ -3,13 +3,14 @@
 Run agentevals alongside [kagent](https://github.com/kagent-dev/kagent) on Kubernetes to evaluate AI agent conversations in real time. This example deploys three components:
 
 1. **agentevals** receives OTLP traces over HTTP and serves the evaluation UI
-2. **OTel Collector** bridges the protocol gap: kagent exports traces via gRPC, but agentevals only supports OTLP/HTTP today, so the Collector converts gRPC to HTTP
+2. **OTel Collector** Optional, useful when you want centralized telemetry
+controls.
 3. **kagent** provides Kubernetes-native AI agents with built-in OTel instrumentation (gRPC export only)
 
 ```
-kagent (gRPC :4317) --> OTel Collector --> agentevals (HTTP :4318)
-                                              |
-                                         UI on :8001
+kagent (gRPC :4317) --> OTel Collector( optional ) --> agentevals (gRPC :4317 / HTTP :4318)
+                                                           |
+                                                      UI on :8001
 ```
 
 ## Prerequisites
@@ -33,12 +34,20 @@ This creates a single pod exposing:
 | Port | Purpose |
 |------|---------|
 | 8001 | Web UI and API |
+| 4317 | OTLP gRPC receiver (traces and logs) |
 | 4318 | OTLP HTTP receiver (traces and logs) |
 | 8080 | MCP (Streamable HTTP) |
 
-### 2. OTel Collector (gRPC to HTTP bridge)
+### 2. OTel Collector (optional)
 
-kagent exports traces over gRPC (port 4317), but agentevals accepts OTLP over HTTP (port 4318). The OTel Collector bridges the two protocols.
+Native gRPC ingestion in agentevals is sufficient for most setups, but an
+intermediate collector is still useful when you want centralized telemetry
+controls:
+
+- traffic shaping (batching, retries, backpressure)
+- filtering or redaction before data reaches agentevals
+- routing/fan-out to additional backends
+- protocol translation for mixed clients
 
 ```bash
 helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
@@ -51,15 +60,15 @@ helm upgrade --install otel-collector open-telemetry/opentelemetry-collector \
   --set image.repository=otel/opentelemetry-collector \
   --set ports.otlp.enabled=true \
   --set ports.otlp-http.enabled=false \
-  --set config.exporters.otlphttp.endpoint="http://agentevals.default.svc.cluster.local:4318" \
-  --set config.exporters.otlphttp.compression="none" \
+  --set config.exporters.otlp.endpoint="agentevals.default.svc.cluster.local:4317" \
+  --set config.exporters.otlp.compression="gzip" \
   --set config.service.pipelines.traces.receivers[0]=otlp \
-  --set config.service.pipelines.traces.exporters[0]=otlphttp \
+  --set config.service.pipelines.traces.exporters[0]=otlp \
   --set config.service.pipelines.logs.receivers[0]=otlp \
-  --set config.service.pipelines.logs.exporters[0]=otlphttp
+  --set config.service.pipelines.logs.exporters[0]=otlp
 ```
 
-> **Note:** If you deployed agentevals in a namespace other than `default`, update the `endpoint` value accordingly: `http://agentevals.<namespace>.svc.cluster.local:4318`.
+> **Note:** If you deployed agentevals in a namespace other than `default`, update the `endpoint` value accordingly: `http://agentevals.<namespace>.svc.cluster.local:4317`.
 
 ### 3. kagent
 
@@ -89,6 +98,8 @@ helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
 
 This installs kagent with only the default Helm agent (`helm-agent`) and the K8s troubleshooter enabled, and points its OTel exporter at the Collector.
 
+> **Note:** If you are not running an OTel Collector, point `otel.tracing.exporter.otlp.endpoint` directly to the agentevals OTLP gRPC endpoint instead: `agentevals.default.svc.cluster.local:4317`.
+
 ### Verify the deployment
 
 ```bash