Connecting to an Observability Platform

Connecting to an Observability Platform#

Squirro produces telemetry through OpenTelemetry and sends it to a collector endpoint that you configure. Because the data uses the standard OpenTelemetry Protocol (OTLP), you can route it to whichever observability platform you already use, including Grafana and Langfuse.

This page describes how to connect Squirro to common platforms. For background on how OpenTelemetry is integrated into Squirro and how to turn it on, see the Observability and Telemetry page.

Squirro exports traces and logs. It does not emit a separate OpenTelemetry metrics signal, so build dashboards and alerts around traces and logs. Language model token usage is still available: it is recorded as attributes on the GenAI trace spans and travels inside OTLP with the traces, which lets a platform such as Langfuse derive cost from it. The host names in the examples below, such as otel-collector:4317, are placeholders. Replace them with the address of your own collector or platform.

The observability platforms described on this page, such as Grafana and Langfuse, and the OpenTelemetry Collector, are third-party software. They are not part of the Squirro platform, and Squirro does not provide, host, or support them. Squirro support covers the telemetry that Squirro produces and how to configure its export. Installing, operating, and troubleshooting the receiving platform and the collector are your responsibility, governed by the terms of the respective vendor.

Before You Begin#

Confirm the following before you connect to an observability platform:

  • Telemetry is turned on, as described on the Observability and Telemetry page.

  • You have decided where to send the telemetry: an OpenTelemetry Collector that forwards the data to your platform, or a platform that exposes an OTLP endpoint directly.

  • The Squirro services can reach that destination over the network.

Squirro does not run a collector by default. Squirro recommends sending telemetry to an OpenTelemetry Collector and letting the collector forward the data to your platform. That approach keeps the Squirro configuration vendor-neutral, lets you change or add platforms without touching Squirro, and gives you a single place to add authentication and to filter sensitive data. The Generic OTLP Collector section below describes how to set up a collector.

Review the sensitive data considerations on the Observability and Telemetry page before you export telemetry to any destination outside your own network. Only the GenAI service sanitizes its own spans, so filter sensitive values at the collector.

Generic OTLP Collector#

The OpenTelemetry Collector is a separate component that you install and run yourself, for example as a container or as a service on a host that the Squirro services can reach. Squirro does not provide or manage it. For installation options, see the OpenTelemetry Collector installation documentation website.

Once the collector is running, point the exporter at its address, replacing the example host name otel-collector:4317 with the address of your own collector:

SQ_OPENTELEMETRY_TRACING=true
SQ_OPENTELEMETRY_EXPORTER_ENDPOINT=otel-collector:4317

Configure the receivers and exporters in the collector itself. That is where you define which platforms receive the data, where you add authentication for a hosted platform, and where you filter sensitive values. A minimal collector configuration that receives over OTLP and forwards to a backend looks as follows:

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  otlphttp:
    endpoint: https://your-backend.example.com
    headers:
      Authorization: "Bearer <token>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      exporters: [otlphttp]

To filter or redact sensitive values before they reach the platform, add processors to the collector pipelines. For the available processors and configuration examples, see the OpenTelemetry Collector transformation documentation website.

Vendors such as Datadog and New Relic document the collector exporter configuration required for their platforms.

Secure and Authenticated Export#

By default, the gRPC exporter uses an insecure connection, set by SQ_OPENTELEMETRY_EXPORTER_INSECURE. A hosted backend usually requires an encrypted connection and an authentication token, so route through a collector and set the encryption and credentials there.

If you must export from Squirro directly to a remote endpoint, set SQ_OPENTELEMETRY_EXPORTER_INSECURE to false and provide the credentials through the exporter configuration section. For the supported keys, see the OpenTelemetry Protocol exporter documentation website.

Grafana#

Grafana stores traces in Tempo and logs in Loki. The Grafana LGTM stack bundles these components together with an OTLP endpoint, which makes it a convenient single destination.

Point the exporter at the Grafana OTLP endpoint, replacing the example host name grafana-lgtm:4317 with the address of your own Grafana endpoint:

SQ_OPENTELEMETRY_TRACING=true
SQ_OPENTELEMETRY_INSTRUMENT_LOGGING=true
SQ_OPENTELEMETRY_EXPORTER_ENDPOINT=grafana-lgtm:4317

After the data arrives, use the Grafana interface to explore traces and to correlate logs with traces. To find a specific request, search traces by service, by operation, or by the squirro.correlation_id attribute.

For a self-contained local setup, Squirro ships a development monitoring stack based on the Grafana LGTM image. Start it with make start-dev-monitoring and open Grafana at http://localhost:3000. For more information on the development monitoring stack, see the Monitoring page.

Langfuse#

Langfuse is an observability platform built for applications that use language models, capturing the prompts, responses, token usage, and agent steps so that you can inspect, debug, and track the cost of AI features. It is most relevant for the GenAI service, where it captures agent runs, prompts, and responses for analysis and debugging. The GenAI service powers AI features in both Squirro and Project Neo. For observability details specific to Project Neo, see the Observability page.

Langfuse is available both as a hosted cloud service and as a self-hostable version. The steps below apply to either one. Sending telemetry to the hosted cloud service means the data, including prompts and responses, leaves your network, so review the personal and regulated data considerations on the Observability and Telemetry page before you use it.

Langfuse accepts OTLP over HTTP only and does not support the gRPC transport. It ingests data through an OTLP HTTP endpoint and authenticates with a public and secret key pair. Because the Squirro exporter defaults to gRPC, routing through an OpenTelemetry Collector also bridges the transport: the collector receives gRPC from Squirro and forwards to Langfuse over HTTP. Squirro sanitizes sensitive values from GenAI spans before they are exported, as described on the Observability and Telemetry page. Language model token usage is recorded as attributes on the GenAI spans, so Langfuse can display token usage from the traces it receives.

Squirro recommends routing telemetry to Langfuse through an OpenTelemetry Collector. Configure Squirro to send data to the collector, as described in the Generic OTLP Collector section above, then configure an OTLP HTTP exporter in the collector that targets the Langfuse endpoint and carries the authentication header. The Langfuse OTLP endpoint has the following form:

https://<langfuse-host>/api/public/otel

Replace <langfuse-host> with your Langfuse Cloud or self-hosted host name. Using a collector keeps the credentials in one place and avoids per-service configuration. For the exact endpoint, header format, and key generation steps, see the Langfuse OpenTelemetry documentation website.

Verifying the Connection#

After you connect to a platform, confirm that telemetry arrives:

  1. Send a request to Squirro, for example a search or a chat message.

  2. Open the observability platform and look for a recent trace. Telemetry is tagged with the service name, for example squirro.service.genai for the GenAI service.

  3. If no data appears, check the service logs for exporter errors, and confirm that the service can reach the configured endpoint. For the log file locations, see the Monitoring page.

If telemetry does not arrive after these checks, visit the Squirro Support website and submit a technical support request.


Contents