Give a customer, a team or a partner access to part of your logs

Hand out a key that can read your logs, metrics and traces, and only the part you choose: one customer's rows, one team's services, one environment, or everything except what is private. The key can read and nothing else, it can be revoked in a second, and the limit is enforced for every statement it sends, however the statement is written. This page takes you from creating the key to checking that it sees only what it should. Every field, limit and code is in the reference: Observability and the API reference.

You need: observability switched on (Observability, step by step), an admin API key (Developers → API keys, scope Admin) or a signed-in dashboard, your organization id (Account & security → Profile & organization), and something to read: logs, spans or metrics that carry the attribute you want to filter on (for example a tenant attribute on each log line, or a resource attribute such as deployment.environment). To do the same from your code, one of plycdn's server packages (ASP.NET Core, Node.js or Python).

1How it works

  1. You create a query key and, if you want to limit it, a row filter: where to look (a resource attribute, the record's own attribute, or the service name), which attribute, and which values are allowed or not.
  2. The key is shown once. You give it to whoever should read: your customer's tooling, a partner, a support engineer, an exporter.
  3. They send it as Authorization: ApiKey plyq_… on the same read routes you use: query, validate, reference, export, live tail and trace. Everything they read is held to the filter.
  4. Anywhere else the key is refused (query_key_not_allowed), so it cannot change settings, make keys or see volumes.
  5. You revoke it when the work is done. It stops on its next request, and anything it has open (a live tail, a download) is cut within 30 seconds.

2Create a key

In the dashboard: Monitoring & logs → Query keys → Create query key. Name it for who will use it (for example acme support). Under Which rows can it read? choose All rows (read only), or Only rows that match and add rules:

  • Rows must match all of the rules or any of them.
  • Each rule has Where to look (Resource attribute, Record attribute, Record attribute, else resource attribute or Service name), the attribute's Name, is or is not, and the Values (one per line).

Press Create key. The key is shown once, under Copy the key for “acme support” now: copy it into your secret store, then choose I have saved it. The dashboard builds one level of rules; the API takes groups nested up to three deep.

From your code:

POST /api/content/v1/observability/query-keys
{"name": "acme support", "rowFilter": {"all": [
    {"source": "attribute_or_resource", "key": "tenant", "in": ["ACME"]},
    {"source": "service", "notIn": ["billing"]}]}}

ASP.NET Core (inject PlycdnObservabilityApi from Plycdn.AspNetCore.Storage)

var filter = QueryKeyRowFilter.AllOf(
    QueryKeyRowFilter.Match("attribute_or_resource", "tenant", "ACME"),
    QueryKeyRowFilter.Except("service", null, "billing"));
var created = await observability.CreateQueryKeyAsync(orgId, new QueryKeyCreate("acme support", filter));
await secrets.SaveAsync("acme-support-query-key", created.Key);   // shown once

Node.js

import { PlycdnStorageApi } from '@plycdn/node/storage';
import { PlycdnObservabilityApi } from '@plycdn/node/observability';

const admin = new PlycdnObservabilityApi(new PlycdnStorageApi({ apiKey: process.env.PLYCDN_ADMIN_KEY! }));
const created = await admin.createQueryKey(orgId, { name: 'acme support', rowFilter: { all: [
  { source: 'attribute_or_resource', key: 'tenant', in: ['ACME'] },
  { source: 'service', notIn: ['billing'] }] } });
await secrets.save('acme-support-query-key', created.key);        // shown once

Python

import os
from plycdn.observability import PlycdnObservabilityApi
from plycdn.storage import PlycdnStorageApi

admin = PlycdnObservabilityApi(PlycdnStorageApi(os.environ["PLYCDN_ADMIN_KEY"]))
created = admin.create_query_key(org_id, {"name": "acme support", "rowFilter": {"all": [
    {"source": "attribute_or_resource", "key": "tenant", "in": ["ACME"]},
    {"source": "service", "notIn": ["billing"]}]}})
secrets.save("acme-support-query-key", created["key"])            # shown once

Leave rowFilter out for a key that reads everything, read-only.

Reading the filter

Part Meaning
source: "resource" The attribute is one of the resource attributes (the sender: service version, environment, host).
source: "attribute" The attribute is one of the record's own attributes (a log line's, a span's, a metric point's).
source: "attribute_or_resource" The record's own attribute decides when it has the key; otherwise the resource attribute does. A record whose own tenant is GLOBEX is outside ["ACME"] even when its resource says ACME.
source: "service" The service name. No key.
in The value is one of the listed values. A row without the attribute does not match.
notIn The exact opposite of in. A row without the attribute matches notIn. For attribute_or_resource, a row with neither attribute matches too.
all / any Every part, or at least one part. Up to 3 levels deep.

Limits: 1 to 8 conditions and 1 to 1,000 values in the whole filter; a key name of 1 to 128 characters (letters, digits and . _ - / :); a value of up to 256 characters. Up to 200 query keys are active at once.

Because a missing attribute matches notIn, "everything except the billing service" also lets through records that have no service at all, and "not tenant ACME" lets through records with no tenant. If that is not what you want, add a rule that requires the attribute to exist, for example in with the values you do allow.

3Use the key

The reader uses the key as the API key of their own client, or as a header.

POST /api/content/v1/observability/query
Authorization: ApiKey plyq_YOUR_KEY
{"sql": "SELECT Timestamp, ServiceName, Body FROM obs.logs ORDER BY Timestamp DESC LIMIT 10"}

ASP.NET Core

// the reader's own application: its ApiKey setting is the query key
var rows = await reader.QueryTelemetryAsync(orgId, new TelemetryQuery
{ Sql = "SELECT Timestamp, ServiceName, Body FROM obs.logs ORDER BY Timestamp DESC LIMIT 10" });

Node.js

const reader = new PlycdnObservabilityApi(new PlycdnStorageApi({ apiKey: process.env.ACME_QUERY_KEY! }));
const rows = await reader.queryTelemetry(orgId, { sql: 'SELECT Timestamp, ServiceName, Body FROM obs.logs ORDER BY Timestamp DESC LIMIT 10' });

Python

reader = PlycdnObservabilityApi(PlycdnStorageApi(os.environ["ACME_QUERY_KEY"]))
rows = reader.query_telemetry(org_id, {"sql": "SELECT Timestamp, ServiceName, Body FROM obs.logs ORDER BY Timestamp DESC LIMIT 10"})

The same client can export (ExportTelemetryAsync, exportTelemetry, export_telemetry), follow logs (TailLogsAsync, tailLogs, tail_logs), open a trace and read the reference. What the key reads is held to its filter in all of them; a trace is found only through rows inside the filter.

Two things differ from an admin key:

  • stats carries elapsedMs only. readRows and readBytes are null (in Node.js and Python) or 0 (in .NET) for a filtered key.
  • The key reads, and nothing else: listQueryKeys, getObservabilitySettings and the other calls answer 403 query_key_not_allowed.

4In the browser

There is nothing to add to the React or Angular packages. A query key is a secret that reads your data: keep it on a server, and have the server run the query for what your page shows.

5Revoke a key

In the dashboard: Monitoring & logs → Query keys, Revoke on the key's row, type the key's name and choose Revoke key. A revoked key shows as Revoked.

From your code:

DELETE /api/content/v1/observability/query-keys/{id}
await observability.RevokeQueryKeyAsync(orgId, key.Id);
await admin.revokeQueryKey(orgId, key.id);
admin.revoke_query_key(org_id, key["id"])

It stops on the next request. A tail or a download the key has open is cut within 30 seconds. Revoking one already revoked changes nothing. A key made with an admin API key also stops when that API key is deactivated or expires, so rotate the admin key and remember to make the query keys again.

6Check it works

  1. Create a key with the filter tenant in ["ACME"] (source Record attribute, else resource attribute).
  2. Send two log lines, one with tenant ACME and one with tenant GLOBEX.
  3. With the key, run SELECT count() FROM obs.logs. The count includes the ACME line and not the GLOBEX line.
  4. With the key, call GET /api/content/v1/observability/volumes. The answer is 403 query_key_not_allowed.
  5. Revoke the key and repeat step 3: the answer is 401.
  6. In Monitoring & logs → Query keys, the key shows its Last used time and, once revoked, Revoked.

7Questions and problems

403 query_key_not_allowed. A query key reads only. The six routes it may call are query, validate, reference, export, tail and trace. For anything else use an admin key.

401 with a key that worked. The key was revoked, or it was made with an admin API key that has since been deactivated or has expired. Make a new one.

409 query_key_limit_reached. Two hundred query keys are active. Revoke the ones you no longer use.

422 validation_error on creating. The name is empty or over 100 characters, or the filter breaks a rule: the detail says which (an unknown source, a key with a character not allowed, both in and notIn, more than 8 conditions or 1,000 values, groups nested more than 3 deep).

403 not_included_in_plan. Your plan does not include observability.

403 admin_key_required. Creating, listing and revoking keys needs an admin key or the dashboard.

404 query_key_not_found. The id is not one of this organization's keys.

429 query_busy. Retryable. Eight statements are already running for your organization, the key's among them. Wait for Retry-After.

The key sees nothing, or too much. Check where the attribute is: attribute reads the record's own attributes, resource the sender's. If a record may have it in either place, use Record attribute, else resource attribute. And remember that a row without the attribute matches is not.

The answer has readRows: null. That is expected for a filtered key; only elapsedMs is reported.

Every code: Errors.