Data-source connectors

Data-source connectors attach Shield360 to observability backends for reading traces, logs, and metrics. Each connector is atomic: one Tempo instance, one Loki instance, one Prometheus endpoint.

Configure them from Settings → Integrations → Connectors (/connectors) or manage bindings from Organization → Project → Connectors. Select the correct project and environment before adding or binding connectors.

Note

Several read paths use portable @openplait adapters so query behavior stays consistent across backends. See the Connectors overview for memory connectors and shared registry concepts.

Mental model

flowchart LR
  subgraph org [Organisation]
    proj[Project]
  end
  subgraph env [Environment]
    bindT[traces binding]
    bindL[logs binding]
    bindM[metrics binding]
  end
  proj --> env
  bindT --> C1[Connector A]
  bindL --> C2[Connector B]
  bindM --> C3[Connector C]
  C1 --> Tempo[Tempo]
  C2 --> Loki[Loki]
  C3 --> Prom[Prometheus]

• Atomic connectors — never a multi-backend blob. One Tempo instance, one Loki instance, one Prometheus endpoint.
• Signal routing — each of traces / logs / metrics is bound independently. See Signal routing.
• Database Config — ClickHouse lives as a Database Config and appears as the built-in connector. See Database Config.

Supported connectors (Shield360 + OpenPlait)

These are the data-source connectors available in Shield360. OpenPlait packages power the portable query adapters for ClickHouse, Tempo, Loki, Prometheus, and Jaeger.

Built-in app store

Connector	Package / implementation	Signals	What it’s for
ClickHouse	Database Config + @openplait/adapter-clickhouse	traces, logs, metrics (+ intelligence)	Default store; full correlation, raw SQL, evals metadata, vault

External data-source connectors

Connector	Package / implementation	Signals	What it’s for
Grafana Tempo	@openplait/adapter-tempo	traces	TraceQL search, trace tree, span events
Grafana Loki	@openplait/adapter-loki	logs	LogQL logs; correlate by trace id / service
Prometheus	@openplait/adapter-prometheus	metrics	PromQL HTTP API (also works with Prometheus-compatible endpoints such as Mimir when you point at their query URL)
Jaeger	@openplait/adapter-jaeger	traces	Jaeger Query HTTP API; sampled in-process aggregates

Tip

Prometheus-compatible APIs (for example Grafana Mimir’s PromQL endpoint) use the Prometheus connector — there is no separate Mimir connector type in Shield360.

Capability matrix

Connector	Signals	Trace tree	Span events	Server aggregation	Raw SQL	Cross-signal correlation
ClickHouse	traces, logs, metrics	Yes	Yes	Yes	Yes	Full
Tempo	traces	Yes	Yes	No*	No	trace / span / service
Loki	logs	—	—	No	No	trace id, service
Prometheus	metrics	—	—	Yes	No	—
Jaeger	traces	Yes	Yes	No*	No	trace / span / service

* Aggregate graphs are reconstructed in-process from a bounded sample of full traces when the backend cannot aggregate server-side.

Fields shared by HTTP connectors

Grafana Tempo, Grafana Loki, Prometheus and Jaeger use the same add dialog (Add source). The setup sections below refer to these fields by their exact labels.

Section	Field	What to enter
Connector	Type	The connector type. It cannot be changed after the connector is saved.
Connection details	Name	A name you will recognise. Names must be unique within an environment.
Connection details	Environment	The environment this connector serves, for example production.
Connection settings	Endpoint URL	The backend’s query API base URL. Shield360 adds the API path itself, so do not include /api/... routes.
Connection settings	Allow plain HTTP (self-hosted)	On by default. Turn it off to require https://.
Connection settings	Allow private or localhost endpoints	Off by default. Turn it on only for localhost, private (RFC 1918) or in-cluster addresses. Cloud metadata addresses stay blocked either way.
Authentication	Authentication type	No authentication, Basic (username + password) or Bearer token.
Authentication	Tenant / Org ID	Tempo, Loki and Prometheus only. Sent as the X-Scope-OrgID header for multi-tenant self-hosted backends. Leave blank for Grafana Cloud.
Authentication	Username / Instance ID and Password / Access policy token	Shown for Basic. For Grafana Cloud, the stack’s instance (user) ID and an access policy token.
Authentication	Bearer token (optional)	Shown for Bearer.
—	Set as project default	Optional.

Credentials are stored encrypted in the Shield360 vault and decrypted only on the server. When you edit a connector, leave a credential blank to keep the stored value.

Note

Test connection works on saved connectors only. Save first, then use Test connection on the connector’s row or in its details dialog. An unsaved connector shows “Save the connector before testing the connection.”

Tip

When Shield360 runs in Docker, localhost means the container, not the host. Use http://host.docker.internal:<port> for services on the host, or the Compose service name (for example http://loki:3100) on the same network, and turn on Allow private or localhost endpoints.

Set up ClickHouse

ClickHouse is Shield360’s own data store: traces, logs and metrics, plus evaluations, rules, the vault and other platform data. Each project environment has one ClickHouse database configuration. See Database Config for how it relates to environment variables.

Note

In the cloud edition Shield360 runs the ClickHouse data store for you and the connector cannot be changed (“The data store is managed by the platform in this edition and cannot be changed here.”). These steps apply to self-hosted installations.

What you’ll need

• A ClickHouse server whose HTTP interface (port 8123 by default) the Shield360 server can reach.
• An empty database for this project and environment. Shield360 does not create the database; it creates the tables inside it.
• A ClickHouse user with the privileges below on that database only.

Privileges. Saving the connector runs Shield360’s ClickHouse migrations on the database, and Shield360 writes platform data to it after that. The user needs more than SELECT. Grant the privileges on the one database only, not *.*:

CREATE DATABASE IF NOT EXISTS shield360_prod;
CREATE USER shield360 IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, ALTER, CREATE TABLE, DROP TABLE, DROP VIEW, OPTIMIZE
  ON shield360_prod.* TO shield360;

This list comes from the statements in this release’s migrations and platform writes: CREATE TABLE IF NOT EXISTS, ALTER TABLE … ADD COLUMN / ADD INDEX / MATERIALIZE INDEX / MODIFY TTL / UPDATE, DELETE FROM, DROP TABLE, DROP VIEW, RENAME TABLE, OPTIMIZE and INSERT. If a later release needs more, saving fails with a ClickHouse ACCESS_DENIED error that names the missing privilege. Every project must use its own database.

Note

TLS. To connect over HTTPS, for example to ClickHouse Cloud, enter the host as an https:// URL (https://abc123.us-east-1.aws.clickhouse.cloud), or use port 8443 or 9440, which mean HTTPS when the host has no scheme. A connector saved through the API can also send secure: true. Any other host without a scheme connects over plain HTTP, as before. Shield360 stores the scheme with the host, and every connection, including validation and Test connection, uses it.

Prepare the database and user

Create the database and user and grant the privileges above. See ClickHouse’s access control guide for CREATE USER and GRANT.

Select project and environment

Use the header selectors to pick the project and environment this database serves.

Open the add dialog

Go to Settings → Integrations → Connectors, choose Add connector, and set Type to ClickHouse.

Fill in the connection

• Name and Environment: one ClickHouse database per environment. A second database for the same environment is refused.
• Username: the ClickHouse user, for example shield360.
• Host: a host name or address, for example clickhouse.internal, or an http:// or https:// URL with an optional port, for example https://clickhouse.example.com:8443. Use https:// for TLS. The URL can’t contain a path, query or credentials. Private network addresses are allowed; cloud metadata addresses are refused.
• Port: the HTTP interface port, usually 8123, or 8443 for HTTPS. If the host URL also has a port, the two must match.
• Database: the database you created, for example shield360_prod.
• Password: the user’s password. It is stored encrypted.
• Query params (optional): key=value pairs joined with &. Shield360 sends each pair as an HTTP header on every ClickHouse request. Leave it blank unless your ClickHouse proxy needs extra headers.
• Traces table, Logs table and Metrics table: the tables Shield360 reads. Leave the defaults (otel_traces, otel_logs, otel_metrics) unless your collector writes elsewhere. Metrics table is a prefix: Shield360 reads <prefix>_gauge, <prefix>_sum and the other metric tables. Each name may use letters, numbers and underscores and can’t start with a number. Shield360’s own migrations and ingest still write the default tables.

Save

Click Save. Shield360 first runs SELECT 1 against the database. If that works, it saves the configuration, runs its migrations, and binds traces, logs and metrics for the environment to this database. Saving can take a little while on a new database.

Test the connection

Use Test connection on the ClickHouse row. Shield360 pings that row’s own database with its own host and credentials, not the environment you have selected. A working connection shows “Data source is reachable.”

Message	What to do
OpenPlait ClickHouse validation failed: …	Shield360 could not run SELECT 1. Check Host, Port (the HTTP port, not the native 9000 port), Username and Password, and that the server can reach ClickHouse.
Enter the ClickHouse host as a name or address, or as an http:// or https:// URL.	Host uses a scheme other than http:// or https://. Remove it, or use https://.
The ClickHouse URL can only hold a scheme, host and port: no path, query or credentials.	Remove the path, query string or user:password@ from Host. Put credentials in Username and Password.
The port in the host URL differs from the port field. Use one of them.	Make the port in Host match Port, or remove one of them.
The host URL starts with http:// but TLS is switched on. Use https:// or switch TLS off.	The host’s scheme and the secure setting disagree. Make them match.
Enter a ClickHouse port between 1 and 65535.	Fix Port.
<Traces table / Logs table / Metrics table prefix> must be a table name: …	Use only letters, numbers and underscores, not starting with a number.
That ClickHouse connector is not in this project, or you cannot see it.	Test connection was run on a connector outside the selected project, or one you don’t have access to. Switch to its project.
No host provided / No port provided / No database provided / No username provided	Fill in the missing field.
That ClickHouse database is already used by another project. …	Each project needs its own database. Create a new one.
This project already has a database for "<environment>" ("<name>"). …	Edit the existing configuration, or create a new environment for the second database.
DB config Name already exists	Choose another Name.
A ClickHouse ACCESS_DENIED or Not enough privileges error on save	The user is missing a privilege the migrations need. Grant it on the database and save again.
The data store is managed by the platform in this edition and cannot be changed here.	Cloud edition. The data store is managed for you.

Set up Grafana Tempo

Use a Grafana Tempo connector to read traces with TraceQL from Grafana Cloud Traces or a self-hosted Tempo. Shield360 reads only; it never writes to Tempo.

What you’ll need

• The Tempo query URL. For Grafana Cloud it usually ends in /tempo.
• For Grafana Cloud: the Tempo instance (user) ID and an access policy token with the traces:read scope.
• For self-hosted Tempo: credentials if a proxy protects it, and the tenant ID if multi-tenancy is on.
• Network access from the Shield360 server to the Tempo query API.

Get the endpoint and instance ID

Grafana Cloud: in the Grafana Cloud Portal, open your stack and the Details page for Tempo. Copy the URL (for example https://tempo-prod-04-prod-us-east-0.grafana.net/tempo) and the user (instance) ID. See Grafana Cloud Traces.

Self-hosted: use the Tempo query frontend URL, for example http://tempo:3200.

Create a read-only token (Grafana Cloud)

Create an access policy limited to this stack with only the traces:read scope, then create a token for it. Shield360 only calls Tempo’s read APIs (/api/status/buildinfo, /api/search, /api/traces/{id}, tag search and /api/metrics/query_range), so it needs no write scope.

Add the connector

Select the project and environment in the header, go to Settings → Integrations → Connectors, choose Add connector, and set Type to Grafana Tempo.

Fill in the fields

• Endpoint URL: the URL from step 1, including /tempo for Grafana Cloud.
• Authentication type: Basic (username + password) for Grafana Cloud. For self-hosted, use No authentication, or Basic or Bearer if your proxy needs it.
• Username / Instance ID: the Tempo instance ID. Password / Access policy token: the token from step 2.
• Tenant / Org ID: self-hosted multi-tenant Tempo only (X-Scope-OrgID).
• Maximum query window (days) (optional): cap the time range Shield360 asks for. Placeholder 30.
• Tempo version (optional): leave blank; the health check detects it.
• Enable experimental most-recent search hint: leave off unless your Tempo supports it.
• TraceQL metrics window hours (optional): limit for TraceQL metrics queries. Placeholder 24.

Save and test

Save, then click Test connection. Shield360 calls /api/status/buildinfo. If the gateway hides that route (403 or 404), it runs a small search over the last five minutes instead. It then looks for AI telemetry from the last hour: “Reachable, and N AI telemetry records found in the last hour.” or “Reachable, but no AI telemetry was found in the last hour.”

Bind traces

Route traces to the connector in Signal routing.

Message	What to do
Data source responded 401: … with the Grafana Cloud hint	Use Basic: Username / Instance ID = instance ID, Password / Access policy token = token. Leave Bearer blank.
Data source responded 403: …	The token is missing traces:read, or its policy does not cover this stack.
Data source responded 404: …	Check the Endpoint URL. Grafana Cloud URLs end in /tempo.
<name> is configured for basic authentication, but its credentials could not be resolved.	Basic or Bearer is selected but no credential is saved. Enter it and save again.
Reachable, but no AI telemetry was found in the last hour.	The connection works. Confirm your apps send gen_ai.* or coding_agent.* attributes or use the Shield360 SDK.

See Common connection errors for network and URL errors.

Set up Grafana Loki

Use a Grafana Loki connector to read logs with LogQL from Grafana Cloud Logs or a self-hosted Loki, and correlate them with traces by trace ID and service.

What you’ll need

• The Loki base URL, for example https://logs-prod-006.grafana.net or http://loki:3100.
• For Grafana Cloud: the Loki instance (user) ID and an access policy token with the logs:read scope.
• For self-hosted Loki: credentials if a proxy protects it, and the tenant ID if auth_enabled is on.
• Network access from the Shield360 server to Loki.

Get the endpoint and instance ID

Grafana Cloud: in the Grafana Cloud Portal, open your stack and the Details page for Loki. Copy the URL and the user (instance) ID. See Grafana Cloud Logs.

Self-hosted: use the Loki base URL, for example http://loki:3100. Do not add /loki/api/v1; Shield360 adds it.

Create a read-only token (Grafana Cloud)

Create an access policy limited to this stack with only the logs:read scope, and a token for it. Shield360 only calls /loki/api/v1/labels, /loki/api/v1/label/{name}/values and /loki/api/v1/query_range.

Add the connector

Select the project and environment in the header, go to Settings → Integrations → Connectors, choose Add connector, and set Type to Grafana Loki.

Fill in the fields

• Endpoint URL: the URL from step 1.
• Authentication type: Basic (username + password) for Grafana Cloud; otherwise what your deployment needs.
• Username / Instance ID and Password / Access policy token: the Loki instance ID and the token.
• Tenant / Org ID: the Loki tenant for multi-tenant self-hosted Loki (X-Scope-OrgID).
• Default LogQL stream selector (optional): the selector used when a query does not give one. Placeholder {service_name=~".+"}.
• Maximum query range (ms) (optional): match your Loki max_query_length. If Loki rejects a range as too long, Shield360 learns the limit from the error and retries with a shorter range.

Save and test

Save, then click Test connection. Shield360 lists label names (/loki/api/v1/labels). A working connection shows “Data source is reachable.” AI-telemetry validation does not apply to log sources.

Bind logs

Route logs to the connector in Signal routing.

Message	What to do
Data source responded 401: … with the Grafana Cloud hint	Set Authentication type to Basic and enter the instance ID and token. If Basic is selected with no username, no Authorization header is sent.
Data source responded 403: …	The token is missing logs:read, or its policy does not cover this stack.
Data source responded 404: …	Use the Loki base URL without /loki/api/v1.
no org id in a self-hosted response	Loki has multi-tenancy on. Fill in Tenant / Org ID.

See Common connection errors for network and URL errors.

Set up Prometheus

Use a Prometheus connector to read metrics with PromQL from Prometheus or a Prometheus-compatible query API, such as Grafana Cloud Metrics or Grafana Mimir. There is no separate Mimir type.

What you’ll need

• The PromQL query base URL, for example http://prometheus:9090 or Grafana Cloud’s …/api/prom.
• For Grafana Cloud: the Prometheus instance (user) ID and an access policy token with metrics:read.
• For Mimir or Cortex: the tenant ID, and credentials if a proxy protects it.
• Network access from the Shield360 server to the query API.

Get the endpoint and instance ID

Grafana Cloud: in the Grafana Cloud Portal, open your stack and the Details page for Prometheus. Copy the query URL ending in /api/prom (not the remote-write URL ending in /push) and the user (instance) ID. See Grafana Cloud Metrics.

Self-hosted: the Prometheus server URL, for example http://prometheus:9090. For Mimir, use its Prometheus API prefix, for example http://mimir:8080/prometheus.

Create a read-only token (Grafana Cloud)

Create an access policy limited to this stack with only metrics:read, and a token for it. Shield360 only calls /api/v1/labels, /api/v1/label/{name}/values and /api/v1/query_range.

Add the connector

Select the project and environment in the header, go to Settings → Integrations → Connectors, choose Add connector, and set Type to Prometheus.

Fill in the fields

• Endpoint URL: the base URL from step 1, without /api/v1.
• Authentication type: Basic (username + password) for Grafana Cloud; No authentication for a default Prometheus; Basic or Bearer behind a proxy.
• Username / Instance ID and Password / Access policy token: the instance ID and token.
• Tenant / Org ID: the Mimir or Cortex tenant (X-Scope-OrgID).
• Default query step: the PromQL step. Default 30s.
• Maximum query range (ms) (optional): cap the range Shield360 queries.

Save and test

Save, then click Test connection. Shield360 lists label names (/api/v1/labels). A working connection shows “Data source is reachable.”

Bind metrics

Route metrics to the connector in Signal routing.

Message	What to do
Data source responded 401: … with the Grafana Cloud hint	Use Basic with the instance ID and a token that has metrics:read.
Data source responded 404: …	The URL is missing /api/prom (Grafana Cloud) or /prometheus (Mimir), or points at the remote-write URL.
no org id in a Mimir response	Fill in Tenant / Org ID.

See Common connection errors for network and URL errors.

Add a Jaeger connector

Use a Jaeger connector to read traces from the Jaeger Query Service HTTP API. Shield360 lists services, searches traces per service, and builds aggregates in process from a bounded sample.

What you’ll need

• The Jaeger Query Service URL, usually on port 16686.
• Credentials only if a proxy protects the query service: Basic or Bearer.
• Network access from the Shield360 server to the query service.

Select project and environment

Use the header selectors to pick the project and environment.

Open Connectors

Go to Settings → Integrations → Connectors and choose Add connector / Add source.

Pick Jaeger

Set Type to Jaeger.

Configure endpoint

• Endpoint URL: the Query Service base URL, for example https://jaeger.example.com or, for a local all-in-one, http://localhost:16686. If the API lives under /jaeger, Shield360 finds it automatically.
• Allow private or localhost endpoints: turn on for localhost or in-cluster addresses.
• Authentication type: No authentication for an unprotected query service. Use Basic (username + password) or Bearer token with credentials from your proxy. Jaeger has no tenant field.

Save and test

Save, then click Test connection. Shield360 calls GET /api/services. Jaeger must return at least one service. Shield360 then looks for AI telemetry from the last hour.

Bind traces

Bind traces to the connector under signal routing.

Tip

Sign in with your administrator account (see First sign-in). Jaeger all-in-one + seed script live in the OpenPlait adapter-jaeger integration folder.

Message	What to do
Jaeger returned no services	The query service is reachable but has no traces yet. Send traces to Jaeger, then test again.
Data source responded 401: …	The proxy needs credentials. Pick Basic or Bearer and enter them.
Data source responded 404: …	The URL is not the Query Service. Use the UI/API port (16686), not a collector port such as 4317, 4318 or 14268.
Host "localhost" is not allowed. …	Turn on Allow private or localhost endpoints. In Docker, use host.docker.internal.

Common connection errors

These messages can come from any HTTP connector: Tempo, Loki, Prometheus, Jaeger, and the memory connectors.

Message	Cause and fix
Save the connector before testing the connection.	Save first, then test.
Host "<host>" is not allowed. Enable "Allow private or localhost endpoints" …	The URL points at localhost or a private address. Turn on Allow private or localhost endpoints if that is intended.
Host "<host>" is not allowed / … resolves to a cloud metadata address	Cloud metadata and link-local addresses are always blocked.
Protocol "http:" is not allowed for this data source	Use https://, or turn on Allow plain HTTP (self-hosted).
Credentials must not be embedded in the URL	Remove user:password@ from the URL and use the authentication fields.
Could not resolve host "<host>"	DNS cannot resolve the host from the Shield360 server.
Data source request timed out	A firewall, security group or proxy is blocking the server, or the backend is slow.
Data source responded <status>: …	The backend returned an error. 401 is authentication, 403 is a missing scope or permission, 404 is a wrong URL path.
Data source response exceeded the 25 MiB safety limit.	Narrow the query or time range.
The connector credential is missing from the Shield360 vault. Re-save the connector credentials.	Edit the connector, enter the credential again, and save.
The connector credential could not be decrypted. Re-save it with the current vault encryption key.	The vault key changed. Enter the credential again and save.

Actions you can take on a connector

The connector registry is designed so actions attach to a connector type. Today’s data-source actions:

Action	When to use it
Add / edit connector	Point Shield360 at a new endpoint or rotate settings
Store credentials in Vault	API keys and tokens stay encrypted; decrypted only server-side
Health check / test connection	Confirm the endpoint is reachable with current auth
Validate AI signal	Confirm recent AI telemetry exists (gen_ai.* / Shield360 markers)
Bind signal	Route traces, logs, or metrics to this connector for an environment
Unbind / rebind	Move a signal to another connector without deleting history in the backend
Mark Database Config active	Choose which ClickHouse app store the UI uses
Share Database Config	Grant edit / delete / re-share on a ClickHouse connection

Enterprise audit logs record connector create/update/delete/test plus bind/unbind (with signal, environment, and previous source when switching).

How Shield360 finds AI telemetry

Backends hold all telemetry — not only AI. Shield360 applies a layered AI selector so reads stay focused:

• Resource telemetry.sdk.name = shield360
• Resource telemetry.distro.name = shield360-cli
• Any gen_ai.* attribute
• coding_agent.session.id, or Claude Code session markers
• Known coding_agent.* span names

Authentication cheat sheet

Backend	Typical auth
Grafana Cloud (Tempo / Loki)	Basic: instance ID + access policy token (traces:read / logs:read). Use query URLs from the Cloud Portal.
Grafana Cloud (Prometheus / Mimir)	Basic: instance ID + access policy token (metrics:read). Use the …/api/prom query URL.
Self-hosted Tempo / Loki / Prometheus / Jaeger	None, Basic, or Bearer; optional tenant / X-Scope-OrgID
ClickHouse	Username / password on the Database Config

Security and reliability

• Endpoints validated (http/https only); credentials in URLs rejected; private/metadata SSRF targets blocked where applicable.
• Secrets live in Vault, redacted from errors, never logged.
• Per-source concurrency caps, query budgets, short-lived cache + in-flight de-dupe, and backoff on transient 429/5xx.

OpenPlait packages

Shield360 wraps these npm packages for portable reads:

npm package	Used for
@openplait/core	Query IR and normalized results
@openplait/adapter-sdk	Adapter contracts
@openplait/adapter-clickhouse	ClickHouse / OTel
@openplait/adapter-tempo	Tempo / TraceQL
@openplait/adapter-loki	Loki / LogQL
@openplait/adapter-prometheus	Prometheus / PromQL
@openplait/adapter-jaeger	Jaeger Query HTTP API
@openplait/runtime	Planning and execution helpers

See the OpenPlait repository for publishing and adapter docs.

Related

Memory connectors

Claude, LangGraph, Mem0, memmesh, and Zep for agent memory.

Scanner connectors

Trustabl scans of GitHub repositories.

Signal routing

Bind traces, logs, and metrics independently.

Database Config

Env vars → ClickHouse Database Config.

Connectors overview

Shared connector model and project scope.