Documentation Grafana Cloud Observe and act Monitor applications Application Observability Set up Instrumentation

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.

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.

For a guided setup, use the Grafana Cloud setup guides.

Resource attributes

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

These attributes map to Prometheus labels as follows:

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:

Native histograms:

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).

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.

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

Next steps

• Navigate to Observability > Application to view your services catalog.
• Review instrumentation quality to identify gaps in your telemetry data.