---
title: "Set up instrumentation | Grafana Cloud documentation"
description: "Instrument your applications with OpenTelemetry and configure Grafana Alloy to send data to Grafana Cloud."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Set up instrumentation

Application Observability requires your applications to be instrumented with OpenTelemetry. The telemetry data flows through Grafana Alloy (or another OpenTelemetry Collector) to Grafana Cloud, where the knowledge graph discovers services and generates insights.

## Instrument your application

Instrumentation is the process of adding code to your application to generate telemetry data (metrics, logs, traces, and profiles).

Grafana Labs supports three instrumentation solutions:

- **Grafana Beyla**: eBPF network-level instrumentation that requires no code changes and supports all languages and frameworks.
- **OpenTelemetry Java SDK**: the Grafana distribution of the OTel Java SDK for process-level telemetry.
- **OpenTelemetry .NET SDK**: the Grafana distribution of the OTel .NET SDK for process-level telemetry.

You can also use community OpenTelemetry SDKs for other languages.

For detailed instructions, refer to the [instrumentation guides](/docs/opentelemetry/instrument/).

## Set up Grafana Alloy

After your application is instrumented, set up Grafana Alloy to send telemetry data to Grafana Cloud. Alloy receives data from your application, processes it, and exports it to the Grafana Cloud OTLP endpoint.

For detailed instructions, refer to the [OpenTelemetry Collector setup documentation](/docs/opentelemetry/collector/).

For a guided setup, use the [Grafana Cloud setup guides](/docs/opentelemetry/grafana-cloud/).

## Resource attributes

Application Observability uses OpenTelemetry resource attributes to identify and organize your services. Configure the following attributes on your applications:

Expand table

| Attribute              | Description                                                           |
|------------------------|-----------------------------------------------------------------------|
| service.namespace      | An optional namespace for `service.name`                              |
| service.name           | The application name                                                  |
| deployment.environment | Name of the deployment environment (`staging` or `production`)        |
| service.instance.id    | The unique instance, for example, the Pod name                        |
| service.version        | The application version, to see if a new version has introduced a bug |

These attributes map to Prometheus labels as follows:

Expand table

| Label    | Derived from                                                                                 |
|----------|----------------------------------------------------------------------------------------------|
| job      | `${service.namespace}/${service.name}` (if `service.namespace` is defined) or `service.name` |
| instance | `service.instance.id`                                                                        |

## Required metrics and labels

Application Observability uses span metrics and service graph metrics to power the services catalog and service detail views. These metrics are generated either by Grafana Cloud Traces or by Grafana Alloy/OTel Collector.

### Common labels

- `job`: identifies services. Concatenation of `$service.namespace/$service.name` or just `service.name` when `service.namespace` isn’t present.
- `deployment_environment`: allows filtering by environment (for example, `prod`, `dev`). Required for the baselines feature.

You can use any additional labels not listed here for filtering or grouping metrics in the UI.

### Target info metric

The `target_info` metric (named `traces_target_info` when generated by Grafana Cloud Traces or Beyla) stores resource attributes. Application Observability derives service inventory and service metadata from this metric.

Required labels: `job`.

Recommended labels:

- `telemetry_sdk_*`: determines service technology and SDK metadata.
- `deployment_environment`: allows filtering by environment.
- `k8s_*`: determines Kubernetes metadata.
- `cloud_*`: determines cloud provider metadata.

### Span metrics

Span metrics power the RED metric panels (latency, error ratio, request rate). Metric names vary by source. Both classic histograms and native histograms are supported.

**Classic histograms:**

Expand table

| Source                                          | Metric names                                                                                                                            |
|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Grafana Cloud Traces, Beyla                     | `traces_spanmetrics_latency_count`, `traces_spanmetrics_latency_sum`, `traces_spanmetrics_latency_bucket`                               |
| Alloy >= v1.5.0, OTel Collector >= v0.109 | `traces_span_metrics_duration_seconds_count`, `traces_span_metrics_duration_seconds_sum`, `traces_span_metrics_duration_seconds_bucket` |
| Alloy v1.0-v1.4.3, OTel Collector v0.94-v0.108  | `duration_seconds_count`, `duration_seconds_sum`, `duration_seconds_bucket`                                                             |

**Native histograms:**

Expand table

| Source                                          | Metric name                            |
|-------------------------------------------------|----------------------------------------|
| Grafana Cloud Traces, Beyla                     | `traces_spanmetrics_latency`           |
| Alloy >= v1.5.0, OTel Collector >= v0.109 | `traces_span_metrics_duration_seconds` |
| Alloy v1.0-v1.4.3, OTel Collector v0.94-v0.108  | `duration_seconds`                     |

Required labels: `job`, `span_kind`, `status_code`, `le` (histogram bucket boundary, classic histograms only).

Recommended labels: `deployment_environment`, `span_name` (operation name for per-operation breakdowns).

### Service graph metrics

Service graph metrics power the service map and inbound/outbound panels. You can disable service graph generation to reduce the number of metric series. Application Observability also uses these metrics to derive uninstrumented services.

**Request count metrics:**

- `traces_service_graph_request_total`
- `traces_service_graph_request_failed_total`

**Latency histogram metrics (classic):**

- `traces_service_graph_request_client_seconds_bucket`, `traces_service_graph_request_client_seconds_count`, `traces_service_graph_request_client_seconds_sum`
- `traces_service_graph_request_server_seconds_bucket`, `traces_service_graph_request_server_seconds_count`, `traces_service_graph_request_server_seconds_sum`

**Latency histogram metrics (native):**

- `traces_service_graph_request_client_seconds`
- `traces_service_graph_request_server_seconds`

Required labels: `client`, `client_service_namespace`, `server`, `server_service_namespace`, `le` (classic histograms only).

Recommended labels: `client_deployment_environment`, `server_deployment_environment`, `connection_type` (determines if a service or database is instrumented).

> Note
> 
> Service graph metrics don’t have `job` labels. Application Observability parses the `job` label from other metrics to derive service namespace and name, which are then used to match `client`/`client_service_namespace` and `server`/`server_service_namespace` respectively.

### Host identification

Application Observability identifies hosts for host-hours billing from standard OpenTelemetry resource attributes attached to your telemetry: `k8s.node.name`, `host.id`, or `grafana.host.id`. For details on priority tiers and per-environment configuration, refer to [Host-hours pricing](/docs/grafana-cloud/observe-and-act/monitor-applications/application-observability-kg/pricing/).

### Runtime metrics

Application Observability uses runtime metrics to display resource utilization data for JVM, Go, and .NET applications.

Required labels: `job`.

Recommended labels: `instance` (correlates CPU/memory usage to a particular instance).

**JVM metrics:**

- `jvm_class_count`
- `process_runtime_jvm_classes_current_loaded`
- `jvm_classes_loaded`
- `jvm_memory_used`, `jvm_memory_used_bytes`
- `jvm_memory_limit`, `jvm_memory_limit_bytes`
- `process_runtime_jvm_memory_usage`, `process_runtime_jvm_memory_usage_bytes`
- `process_runtime_jvm_memory_limit`, `process_runtime_jvm_memory_limit_bytes`
- `jvm_memory_max`, `jvm_memory_max_bytes`
- `jvm_gc_duration_sum`, `jvm_gc_duration_seconds_sum`
- `process_runtime_jvm_gc_duration_sum`, `process_runtime_jvm_gc_duration_seconds_sum`
- `jvm_gc_pause_sum`, `jvm_gc_pause_seconds_sum`, `jvm_gc_pause_milliseconds_sum`
- `jvm_cpu_recent_utilization`, `jvm_cpu_recent_utilization_ratio`
- `process_runtime_jvm_system_cpu_utilization`, `process_runtime_jvm_system_cpu_utilization_ratio`
- `system_cpu_usage`
- `jvm_thread_count`
- `process_runtime_jvm_threads_count`
- `jvm_threads_live`

**Go metrics:**

- `process_runtime_go_mem_live_objects`
- `process_runtime_go_mem_heap_sys`
- `process_runtime_go_mem_heap_alloc`, `process_runtime_go_mem_heap_alloc_bytes`
- `process_runtime_go_mem_heap_idle`, `process_runtime_go_mem_heap_idle_bytes`
- `process_runtime_go_mem_heap_inuse`, `process_runtime_go_mem_heap_inuse_bytes`
- `process_runtime_go_mem_heap_released`, `process_runtime_go_mem_heap_released_bytes`
- `process_runtime_go_mem_lookups`, `process_runtime_go_mem_lookups_total`
- `process_runtime_go_mem_heap_objects`
- `process_runtime_go_goroutines`
- `process_runtime_go_gc_count`, `process_runtime_go_gc_count_total`
- `process_runtime_go_cgo_calls`

**.NET metrics:**

- `process_runtime_dotnet_gc_objects_size`, `process_runtime_dotnet_gc_objects_size_bytes`
- `process_threads`, `process_thread_count`
- `process_cpu_time`, `process_cpu_time_seconds_total`
- `process_memory_usage`, `process_memory_usage_bytes`

> Note
> 
> You can use any additional labels not mentioned here for filtering metrics in the UI.

## Next steps

- Navigate to **Observability > Application** to view your [services catalog](/docs/grafana-cloud/observe-and-act/monitor-applications/application-observability-kg/services/).
- Review [instrumentation quality](/docs/grafana-cloud/observe-and-act/monitor-applications/application-observability-kg/services/instrumentation-quality/) to identify gaps in your telemetry data.