CPU and memory profiling

Metrics → Profiles connects an existing Grafana Cloud Profiles stack. It reads bounded CPU, allocated-memory and live-heap graphs, ranks self samples, and links retained trace spans. Profiles remain in Grafana.

Connect and verify

Open your Grafana stack's Profiles connection details. Create a stack-scoped access policy token with profiles:read.
Enter its https://profiles-….grafana.net endpoint, numeric Profiles instance ID, Grafana stack URL and Pyroscope data-source UID. Map local trace service names to external service_name values.
Configure the profiler to attach the exact saaspro_app and saaspro_env identifiers shown in the console. These labels are mandatory in every query. Use the selected release label for version comparisons.
Save the connection and run a profile query. “Connected; no matching profiles” means the read protocol succeeded but supplied no matching samples. It does not prove profiling coverage.

Only approved Grafana Cloud Profiles origins are supported in this increment. Arbitrary URLs, redirects and custom ports are refused. The token is envelope-encrypted in the vault and never returned. Replacing/disconnecting a connection revokes its old local credential; revoke the external token in Grafana separately if required.

Collect profiles

Use a supported Pyroscope language SDK or a Grafana Alloy collector in your application's infrastructure. The control plane does not install a profiler or run workloads on your servers. Choose a profiler according to runtime support and review its overhead and data collection.

An Alloy configuration for an existing Go pprof endpoint can add the required labels:

pyroscope.scrape "application" {
  targets = [{
    "__address__" = "application:6060",
    "service_name" = "checkout",
    "saaspro_app" = "APPLICATION_ID_FROM_CONSOLE",
    "saaspro_env" = "ENVIRONMENT_ID_FROM_CONSOLE",
    "service_version" = "RELEASE_ID",
  }]
  forward_to = [pyroscope.write.profiles.receiver]
}

pyroscope.write "profiles" {
  endpoint {
    url = sys.env("PYROSCOPE_URL")
    basic_auth {
      username = sys.env("PYROSCOPE_USERNAME")
      password = sys.env("PYROSCOPE_WRITE_TOKEN")
    }
  }
}

Use a separate profiles:write token on the collector. Keep the application's pprof endpoint private to its collector; the control plane never requests it. Runtime profiler defaults determine which CPU/memory types are available.

Follow a trace

Enable span profiling only after installing the runtime's supported Pyroscope/OpenTelemetry bridge. Open a retained trace, select a span and follow Inspect profiles for this span. Both IDs, service, release and the environment are checked locally. The query uses the span's time window and the provider's dedicated span-selection RPC. Missing or unsupported span profiles remain unavailable; service-wide samples are never substituted.

Without a profiling bridge, Inspect service profiles carries service/release context only. eBPF collection cannot establish per-span correlation.

Interpret the graph

Flame width represents inclusive samples; the table ranks self samples. Click a function to focus it and use Reset graph to return. This is sampled resource cost, not elapsed request duration or utilization. Live-heap samples are aggregated across an interval; their sum is not a single instantaneous heap measurement. Truncation and unknown coverage remain visible.

Function names and technical identifiers may contain personal data. The console requires metrics.read and people.pii.read to query symbols and applies best-effort text redaction. This does not guarantee anonymization. Raw profiles, returned labels and graph contents are not stored in the platform database, audit metadata, local storage or cookies. Results exist in memory until navigation or another query.

Limits and API

One connection and twenty service mappings per environment.
One concurrent query, thirty per minute, two thousand per UTC day.
At most twenty-four hours, capped by application retention; retained-span matching also follows trace retention.
Eight-second provider timeout, 512 KiB response and 1,000 requested graph nodes. Unsupported integers, malformed graphs and oversized responses are refused.
Settings require Metrics write, Credentials write and a passkey verified within ten minutes. All changes and queries are audited. Pause, replacement, disconnect, access revocation or shortened retention during a query discards its result. Expired reservations never start a provider request.

Management API: GET /api/v1/apps/{org}/{app}/metrics/profiles?env=production&service=checkout&type=cpu&range=1h. Optional release, trace and span narrow the query. Types are cpu, allocated, live; ranges are 1h, 6h, 24h. A read-scoped Management token must have Metrics and People PII read permissions. Ingest keys cannot read profiles.

Protocol references

Checked 8 September 2026. Service queries use SelectMergeStacktraces; span queries use the dedicated, backward-compatible SelectMergeSpanProfile RPC. The latter is deprecated upstream but remains supported; unsupported responses fail explicitly. Graph decoding follows Pyroscope's single-profile delta-encoded flamebearer format. Grafana links use the documented Explore pane schema and Pyroscope query fields.