From 6782c766cb192655cf3f52b2fa2c3cf9b5d5ac64 Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:35:11 +0100 Subject: [PATCH 01/13] adds otel kubernetes docs Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- .../guides-k8s/telemetry-and-metrics.md | 282 ++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 docs/toolhive/guides-k8s/telemetry-and-metrics.md diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md new file mode 100644 index 00000000..e40e698c --- /dev/null +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -0,0 +1,282 @@ +--- +title: Telemetry (metrics and traces) +description: + How to enable OpenTelemetry (metrics and traces) and Prometheus + instrumentation for ToolHive MCP servers inside of Kubernetes using the + ToolHive Operator +--- + +ToolHive includes built-in instrumentation using OpenTelemetry, which gives you +comprehensive observability for your MCP server interactions. You can export +traces and metrics to popular observability backends like Jaeger, Honeycomb, +Datadog, and Grafana Cloud, or expose Prometheus metrics directly. + +## What you can monitor + +ToolHive's telemetry captures detailed information about MCP interactions +including traces, metrics, and performance data. For a comprehensive overview of +the telemetry architecture, metrics collection, and monitoring capabilities, see +the [observability overview](../concepts/observability.md). + +## Enable telemetry + +You can enable telemetry when deploying an MCP server by specifying Telemetry +configuration in the `MCPServer` custom resource. + +This example runs the Fetch MCP server and exports traces to a deployed instance +of the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/): + +```yaml +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: gofetch + namespace: toolhive-system +spec: + image: ghcr.io/stackloklabs/gofetch/server + transport: streamable-http + port: 8080 + targetPort: 8080 + ... + ... + telemetry: + openTelemetry: + enabled: true + endpoint: otel-collector-opentelemetry-collector.monitoring.svc.cluster.local:4318 + serviceName: mcp-fetch-server + insecure: true + metrics: + enabled: true + tracing: + enabled: true + samplingRate: "0.05" + prometheus: + enabled: true +``` + +The `spec.telemetry.openTelemetry.endpoint` will be the OpenTelemetry collector +that is deployed inside of your infrastructure, the +`spec.telemetry.openTelemetry.serviceName` will be what you can use to identify +your MCP server in your observability stack. + +### Export metrics to an OTLP endpoint + +If you want to enable ToolHive to export metrics to your OTel collector, you can +enable the `spec.telemetry.openTelemetry.metrics.enabled` flag. + +### Export traces to an OTLP endpoint + +If you want to enable ToolHive to export tracing information, you can enable the +`spec.telemetry.openTelemetry.tracing.enabled` flag. + +You can also set the sampling rate of your traces by setting the +`spec.telemetry.openTelemetry.tracing.sampleRate` option to a number netween 0 +and 1.0. By default this will be `0.05` which equates to 5% of all requests. + +:::note + +The `spec.telemetry.openTelemetry.endpoint` is provided as a hostname and +optional port, without a scheme or path (e.g., use `api.honeycomb.io` or +`api.honeycomb.io:443`, not `https://api.honeycomb.io`). ToolHive automatically +uses HTTPS unless `--otel-insecure` is specified. + +::: + +By default, the service name is set to `toolhive-mcp-proxy`, and the sampling +rate is `0.05` (5%). + +:::tip[Recommendation] + +Set the `spec.telemetry.openTelemetry.serviceName` flag to a meaningful name for +each MCP server. This helps you identify the server in your observability +backend. + +::: + +### Enable Prometheus metrics + +You can expose Prometheus-style metrics at `/metrics` on the main transport port +for local scraping by enabling the `spec.telemetry.prometheus.enabled` flag. + +To access the metrics, you can use `curl` or any Prometheus-compatible scraper. +The metrics are available at `http://:/metrics`, where `` is the port of which the ProxyRunner service is configured to expose +for traffic. + +### Dual export + +You can export to both an OTLP endpoint and expose Prometheus metrics +simultaneously. + +The `MCPServer` example at the top of this page has dual export enabled. + +## Observability backends + +ToolHive can export telemetry data to many different observability backends. It +supports exporting traces and metrics to any backend that implements the OTLP +protocol. Some common examples are listed below, but specific configurations +will vary based on your environment and requirements. + +### OpenTelemetry Collector (recommended) + +The OpenTelemetry Collector is a vendor-agnostic way to receive, process and +export telemetry data. It supports many backend services, scalable deployment +options, and advanced processing capabilities. + +```mermaid +graph LR + A[ToolHive] -->|traces & metrics| B[OpenTelemetry Collector] + B --> C[AWS CloudWatch] + B --> D[Splunk] + B --> E[New Relic] + B <--> E[Prometheus] + B --> F[Other OTLP backends] +``` + +You can run the OpenTelemetry Collector inside of a Kubernetes cluster, follow +the +[OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/) +for more information. + +To export data to a local OpenTelemetry Collector, set your OTLP endpoint to the +OTLP http receiver port (default is `4318`): + +```yaml +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: gofetch + namespace: toolhive-system +spec: + ... + ... + telemetry: + openTelemetry: + enabled: true + endpoint: otel-collector-opentelemetry-collector.monitoring.svc.cluster.local:4318 + serviceName: mcp-fetch-server + insecure: true + metrics: + enabled: true +``` + +### Prometheus + +To collect metrics using Prometheus, run your MCP server with the +`spec.telemetry.prometheus.enabled` flag enabled and add the following to your +Prometheus configuration: + +```yaml title="prometheus.yml" +scrape_configs: + - job_name: 'toolhive-mcp-proxy' + static_configs: + - targets: [':'] + scrape_interval: 15s + metrics_path: /metrics +``` + +You can add multiple MCP servers to the `targets` list. Replace +`` with the ProxyRunner SVC name and +`` with the port number exposed by the SVC. + +### Jaeger + +[Jaeger](https://www.jaegertracing.io) is a popular open-source distributed +tracing system. You can run it inside of a Kubernetes cluster in order to store +tracing telemetry data exported by the ToolHive proxy. + +You can export traces to Jaeger by setting the OTLP endpoint to an OpenTelemetry +collector, and then configuring the collector to export tracing data to Jaeger. + +```yaml +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: gofetch + namespace: toolhive-system +spec: + ... + ... + telemetry: + openTelemetry: + enabled: true + endpoint: otel-collector-opentelemetry-collector.monitoring.svc.cluster.local:4318 + serviceName: mcp-fetch-server + insecure: true + tracing: + enabled: true +``` + +Inside of your OpenTelemetry collector configuration. + +```yaml +config: + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + http: + endpoint: 0.0.0.0:4318 + + exporters: + otlp/jaeger: + endpoint: http://jaeger-all-in-one-collector.monitoring:4317 + + service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [otlp/jaeger] +``` + +### Honeycomb + +Coming soon. + +You'll need your Honeycomb API key, which you can find in your +[Honeycomb account settings](https://ui.honeycomb.io/account). + +### Datadog + +Datadog has [multiple options](https://docs.datadoghq.com/opentelemetry/) for +collecting OpenTelemetry data: + +- The + [**OpenTelemetry Collector**](https://docs.datadoghq.com/opentelemetry/setup/collector_exporter/) + is recommended for existing OpenTelemetry users or users wanting a + vendor-neutral solution. + +- The [**Datadog Agent**](https://docs.datadoghq.com/opentelemetry/setup/agent) + is recommended for existing Datadog users. + +### Grafana Cloud + +Coming soon. + +## Performance considerations + +### Sampling rates + +Adjust sampling rates based on your environment: + +- **Development**: `--otel-sampling-rate 1.0` (100% sampling) +- **Production**: `--otel-sampling-rate 0.01` (1% sampling for high-traffic + systems) +- **Default**: `--otel-sampling-rate 0.05` (5% sampling) + +### Network overhead + +Telemetry adds minimal overhead when properly configured: + +- Use appropriate sampling rates for your traffic volume +- Monitor your observability backend costs and adjust sampling accordingly + +## Related information + +- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the + `MCPServer` Custom Resource Definition (CRD) +- [Deploy the operator using Helm](./deploy-operator-helm.md) - Install the + ToolHive operator From 6ef91bf3cc4a1e6dad4ff1358bc2083cf16a28c7 Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:46:49 +0100 Subject: [PATCH 02/13] adds sidebar menu for telemetry docs Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- sidebars.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.ts b/sidebars.ts index 4354277b..a875800a 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -121,6 +121,7 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-k8s/intro', 'toolhive/guides-k8s/deploy-operator-helm', 'toolhive/guides-k8s/run-mcp-k8s', + 'toolhive/guides-k8s/telemetry-and-metrics', 'toolhive/reference/crd-spec', ], }, From f4e0908c9df6ccbec09133d80525b9083a4ce118 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:47:54 +0100 Subject: [PATCH 03/13] Update docs/toolhive/guides-k8s/telemetry-and-metrics.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-k8s/telemetry-and-metrics.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md index e40e698c..983b4fc9 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.md +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -262,11 +262,14 @@ Coming soon. Adjust sampling rates based on your environment: -- **Development**: `--otel-sampling-rate 1.0` (100% sampling) -- **Production**: `--otel-sampling-rate 0.01` (1% sampling for high-traffic - systems) -- **Default**: `--otel-sampling-rate 0.05` (5% sampling) - +- **Development**: + + ```yaml + spec: + telemetry: + openTelemetry: + tracing: + samplingRate: 1.0 # 100% sampling ### Network overhead Telemetry adds minimal overhead when properly configured: From 8e7ee5f4cd5abf60cae3e97fc3c324bf2316cda6 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:48:03 +0100 Subject: [PATCH 04/13] Update docs/toolhive/guides-k8s/telemetry-and-metrics.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-k8s/telemetry-and-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md index 983b4fc9..f70326aa 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.md +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -70,7 +70,7 @@ If you want to enable ToolHive to export tracing information, you can enable the `spec.telemetry.openTelemetry.tracing.enabled` flag. You can also set the sampling rate of your traces by setting the -`spec.telemetry.openTelemetry.tracing.sampleRate` option to a number netween 0 +`spec.telemetry.openTelemetry.tracing.sampleRate` option to a number between 0 and 1.0. By default this will be `0.05` which equates to 5% of all requests. :::note From b185559cb9996dac48be64cb21ebc4f34a37ec96 Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:48:12 +0100 Subject: [PATCH 05/13] Update docs/toolhive/guides-k8s/telemetry-and-metrics.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-k8s/telemetry-and-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md index f70326aa..bb7f20c1 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.md +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -99,7 +99,7 @@ You can expose Prometheus-style metrics at `/metrics` on the main transport port for local scraping by enabling the `spec.telemetry.prometheus.enabled` flag. To access the metrics, you can use `curl` or any Prometheus-compatible scraper. -The metrics are available at `http://:/metrics`, where `:/metrics`, where `` is resolvable address of the ToolHive ProxyRunner fronting your MCP server pod and `` is the port of which the ProxyRunner service is configured to expose for traffic. From f467006d8e55932a59bb75491e4fc2d597a706eb Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:54:45 +0100 Subject: [PATCH 06/13] fixes format issues Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-k8s/telemetry-and-metrics.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md index bb7f20c1..be3ca5f3 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.md +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -262,14 +262,13 @@ Coming soon. Adjust sampling rates based on your environment: -- **Development**: - - ```yaml - spec: - telemetry: - openTelemetry: - tracing: - samplingRate: 1.0 # 100% sampling +- **Development**: `spec.telemetry.openTelemetry.tracing.samplingRate: 1.0` + (100% sampling) +- **Production**: `spec.telemetry.openTelemetry.tracing.samplingRate 0.01` (1% + sampling for high-traffic systems) +- **Default**: `spec.telemetry.openTelemetry.tracing.samplingRate 0.05` (5% + sampling) + ### Network overhead Telemetry adds minimal overhead when properly configured: From e5b4e261600a2cb58a518038f0c346e4d961909d Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 21:58:08 +0100 Subject: [PATCH 07/13] modify mermaid diagram Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-k8s/telemetry-and-metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.md b/docs/toolhive/guides-k8s/telemetry-and-metrics.md index be3ca5f3..d0cf3d97 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.md +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.md @@ -130,8 +130,8 @@ graph LR B --> C[AWS CloudWatch] B --> D[Splunk] B --> E[New Relic] - B <--> E[Prometheus] - B --> F[Other OTLP backends] + B <--> F[Prometheus] + B --> G[Other OTLP backends] ``` You can run the OpenTelemetry Collector inside of a Kubernetes cluster, follow From bf62ddcd816a58d9bafaf314502ede7883920b72 Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 22:14:51 +0100 Subject: [PATCH 08/13] amends CLI docs with new telemetry flags Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- .../guides-cli/telemetry-and-metrics.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index 68defb12..9ef3564f 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -38,6 +38,8 @@ thv run \ --otel-endpoint localhost:4318 \ --otel-service-name fetch-mcp \ --otel-insecure \ + --otel-tracing-enabled \ + --otel-metrics-enabled fetch ``` @@ -70,6 +72,8 @@ context like deployment environment or service version to your traces. ```bash thv run \ --otel-endpoint api.honeycomb.io \ + --otel-tracing-enabled \ + --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-env-vars "NODE_ENV,DEPLOYMENT_ENV,SERVICE_VERSION" \ fetch @@ -113,6 +117,8 @@ This example exports to Honeycomb and enables the Prometheus metrics endpoint: ```bash thv run \ --otel-endpoint api.honeycomb.io \ + --otel-tracing-enabled \ + --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-enable-prometheus-metrics-path \ fetch @@ -132,20 +138,23 @@ when running an MCP server with the `thv run` command: ```bash thv run [--otel-endpoint ] [--otel-service-name ] \ + [--otel-metrics-enabled] [--otel-tracing-enabled] \ [--otel-sampling-rate ] [--otel-headers ] \ [--otel-insecure] [--otel-enable-prometheus-metrics-path] \ ``` -| Flag | Description | Default | -| --------------------------------------- | ----------------------------------------------------------- | -------------------- | -| `--otel-endpoint` | OTLP endpoint (e.g., `api.honeycomb.io`) | None | -| `--otel-service-name` | Service name for telemetry | `toolhive-mcp-proxy` | -| `--otel-sampling-rate` | Trace sampling rate (0.0-1.0) | `0.1` (10%) | -| `--otel-headers` | Authentication headers in `key=value` format | None | -| `--otel-env-vars` | List of environment variables to include in telemetry spans | None | -| `--otel-insecure` | Connect using HTTP instead of HTTPS | `false` | -| `--otel-enable-prometheus-metrics-path` | Enable `/metrics` endpoint | `false` | +| Flag | Description | Default | +| --------------------------------------- | ------------------------------------------------------------- | -------------------- | +| `--otel-endpoint` | OTLP endpoint (e.g., `api.honeycomb.io`) | None | +| `--otel-metrics-enabled` | Enable OTLP metrics export (when OTLP endpoint is configured) | `false` | +| `--otel-tracing-enabled` | Enable distributed tracing (when OTLP endpoint is configured) | `false` | +| `--otel-service-name` | Service name for telemetry | `toolhive-mcp-proxy` | +| `--otel-sampling-rate` | Trace sampling rate (0.0-1.0) | `0.1` (10%) | +| `--otel-headers` | Authentication headers in `key=value` format | None | +| `--otel-env-vars` | List of environment variables to include in telemetry spans | None | +| `--otel-insecure` | Connect using HTTP instead of HTTPS | `false` | +| `--otel-enable-prometheus-metrics-path` | Enable `/metrics` endpoint | `false` | ### Global configuration @@ -162,6 +171,8 @@ rate: ```bash thv config otel set-endpoint api.honeycomb.io +thv config otel set-metrics-enabled true +thv config otel set-tracing-enabled true thv config otel set-sampling-rate 0.25 ``` @@ -204,6 +215,8 @@ OTLP http receiver port (default is `4318`): ```bash thv run \ --otel-endpoint localhost:4318 \ + --otel-tracing-enabled \ + --otel-metrics-enabled \ --otel-insecure \ fetch ``` @@ -240,6 +253,7 @@ by setting the OTLP endpoint to Jaeger's collector: ```bash thv run \ --otel-endpoint localhost:4318 \ + --otel-tracing-enabled \ --otel-insecure \ ``` @@ -256,6 +270,8 @@ forward data to Honeycomb. This example sends data directly to Honeycomb: ```bash thv run \ --otel-endpoint api.honeycomb.io \ + --otel-tracing-enabled \ + --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-service-name production-mcp-proxy \ @@ -290,6 +306,8 @@ You can also send data directly to ```bash thv run \ --otel-endpoint otlp-gateway-prod-us-central-0.grafana.net \ + --otel-tracing-enabled \ + --otel-metrics-enabled \ --otel-headers "Authorization=Basic $(echo -n 'user:password' | base64)" \ ``` From 572a3d9266ac8e60a841ac70717acfe7357836f3 Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Mon, 8 Sep 2025 22:51:04 +0100 Subject: [PATCH 09/13] adds missing flags Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-cli/telemetry-and-metrics.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index 9ef3564f..bf2aa186 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -39,7 +39,7 @@ thv run \ --otel-service-name fetch-mcp \ --otel-insecure \ --otel-tracing-enabled \ - --otel-metrics-enabled + --otel-metrics-enabled \ fetch ``` @@ -174,6 +174,8 @@ thv config otel set-endpoint api.honeycomb.io thv config otel set-metrics-enabled true thv config otel set-tracing-enabled true thv config otel set-sampling-rate 0.25 +thv config otel set-enable-prometheus-metrics-path true +thv config otel set-insecure true ``` Each command has a corresponding `get` and `unset` command to retrieve or remove From f486a8d3ba13ba8858747862cf9093813c533c7a Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 9 Sep 2025 15:14:24 +0100 Subject: [PATCH 10/13] removes unneeded flags Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- .../guides-cli/telemetry-and-metrics.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index bf2aa186..cb7d225f 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -38,8 +38,6 @@ thv run \ --otel-endpoint localhost:4318 \ --otel-service-name fetch-mcp \ --otel-insecure \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ fetch ``` @@ -72,8 +70,6 @@ context like deployment environment or service version to your traces. ```bash thv run \ --otel-endpoint api.honeycomb.io \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-env-vars "NODE_ENV,DEPLOYMENT_ENV,SERVICE_VERSION" \ fetch @@ -117,8 +113,6 @@ This example exports to Honeycomb and enables the Prometheus metrics endpoint: ```bash thv run \ --otel-endpoint api.honeycomb.io \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-enable-prometheus-metrics-path \ fetch @@ -147,8 +141,8 @@ thv run [--otel-endpoint ] [--otel-service-name ] \ | Flag | Description | Default | | --------------------------------------- | ------------------------------------------------------------- | -------------------- | | `--otel-endpoint` | OTLP endpoint (e.g., `api.honeycomb.io`) | None | -| `--otel-metrics-enabled` | Enable OTLP metrics export (when OTLP endpoint is configured) | `false` | -| `--otel-tracing-enabled` | Enable distributed tracing (when OTLP endpoint is configured) | `false` | +| `--otel-metrics-enabled` | Enable OTLP metrics export (when OTLP endpoint is configured) | `true` | +| `--otel-tracing-enabled` | Enable distributed tracing (when OTLP endpoint is configured) | `true` | | `--otel-service-name` | Service name for telemetry | `toolhive-mcp-proxy` | | `--otel-sampling-rate` | Trace sampling rate (0.0-1.0) | `0.1` (10%) | | `--otel-headers` | Authentication headers in `key=value` format | None | @@ -217,8 +211,6 @@ OTLP http receiver port (default is `4318`): ```bash thv run \ --otel-endpoint localhost:4318 \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ --otel-insecure \ fetch ``` @@ -255,7 +247,6 @@ by setting the OTLP endpoint to Jaeger's collector: ```bash thv run \ --otel-endpoint localhost:4318 \ - --otel-tracing-enabled \ --otel-insecure \ ``` @@ -272,8 +263,6 @@ forward data to Honeycomb. This example sends data directly to Honeycomb: ```bash thv run \ --otel-endpoint api.honeycomb.io \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ --otel-headers "x-honeycomb-team=" \ --otel-service-name production-mcp-proxy \ @@ -308,8 +297,6 @@ You can also send data directly to ```bash thv run \ --otel-endpoint otlp-gateway-prod-us-central-0.grafana.net \ - --otel-tracing-enabled \ - --otel-metrics-enabled \ --otel-headers "Authorization=Basic $(echo -n 'user:password' | base64)" \ ``` From c803999fb46b71b66b40af48a094d5a59f820e2a Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 9 Sep 2025 15:31:06 +0100 Subject: [PATCH 11/13] disables metrics for jaeger example Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-cli/telemetry-and-metrics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index cb7d225f..19c2212d 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -263,6 +263,7 @@ forward data to Honeycomb. This example sends data directly to Honeycomb: ```bash thv run \ --otel-endpoint api.honeycomb.io \ + --otel-metrics-enabled=false \ --otel-headers "x-honeycomb-team=" \ --otel-service-name production-mcp-proxy \ From 1176580ff14aef097c95e81abdc8ef27d11f2b77 Mon Sep 17 00:00:00 2001 From: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 9 Sep 2025 15:32:50 +0100 Subject: [PATCH 12/13] oppsie, meant to add to jaeger section Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> --- docs/toolhive/guides-cli/telemetry-and-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index 19c2212d..ada60ebb 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -247,6 +247,7 @@ by setting the OTLP endpoint to Jaeger's collector: ```bash thv run \ --otel-endpoint localhost:4318 \ + --otel-metrics-enabled=false \ --otel-insecure \ ``` @@ -263,7 +264,6 @@ forward data to Honeycomb. This example sends data directly to Honeycomb: ```bash thv run \ --otel-endpoint api.honeycomb.io \ - --otel-metrics-enabled=false \ --otel-headers "x-honeycomb-team=" \ --otel-service-name production-mcp-proxy \ From 245da1b13e9320cc6a4b9e36eef0857b8924097c Mon Sep 17 00:00:00 2001 From: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com> Date: Tue, 9 Sep 2025 15:39:42 +0100 Subject: [PATCH 13/13] Update docs/toolhive/guides-cli/telemetry-and-metrics.md Co-authored-by: Dan Barr --- docs/toolhive/guides-cli/telemetry-and-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.md b/docs/toolhive/guides-cli/telemetry-and-metrics.md index ada60ebb..7dee480e 100644 --- a/docs/toolhive/guides-cli/telemetry-and-metrics.md +++ b/docs/toolhive/guides-cli/telemetry-and-metrics.md @@ -132,7 +132,7 @@ when running an MCP server with the `thv run` command: ```bash thv run [--otel-endpoint ] [--otel-service-name ] \ - [--otel-metrics-enabled] [--otel-tracing-enabled] \ + [--otel-metrics-enabled=] [--otel-tracing-enabled=] \ [--otel-sampling-rate ] [--otel-headers ] \ [--otel-insecure] [--otel-enable-prometheus-metrics-path] \