github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/trace-span-profiles/java-span-profiles.md (about) 1 --- 2 title: Span profiles with Traces to profiles for Java 3 menuTitle: Span profiles with Traces to profiles (Java) 4 description: Learn about and configure Span profiles with Traces to profiles in Grafana for the Java language. 5 weight: 101 6 --- 7 8 # Span profiles with Traces to profiles for Java 9 10 Span Profiles represent a major shift in profiling methodology, enabling deeper analysis of both tracing and profiling data. 11 Traditional continuous profiling provides an application-wide view over fixed intervals. 12 In contrast, Span Profiles delivers focused, dynamic analysis on specific execution scopes within applications, such as individual requests or specific trace spans. 13 14 This shift enables a more granular view of performance, enhancing the utility of profiles by linking them directly with traces for a comprehensive understanding of application behavior. As a result, engineering teams can more efficiently identify and address performance bottlenecks. 15 16 To learn more about Span Profiles, refer to [Combining tracing and profiling for enhanced observability: Introducing Span Profiles](/blog/2024/02/06/combining-tracing-and-profiling-for-enhanced-observability-introducing-span-profiles/). 17 18  19 20 Pyroscope integrates with distributed tracing systems supporting the [**OpenTelemetry**](https://opentelemetry.io/docs/instrumentation/java/getting-started/) standard. 21 This integration lets you link traces with the profiling data and find resource usage for specific lines of code for your trace spans. 22 23 {{< admonition type="note" >}} 24 * Only CPU profiling is supported at the moment. 25 * Because of how sampling profilers work, spans shorter than the sample interval may not be captured. 26 {{< /admonition >}} 27 28 To use Span Profiles, you need to: 29 30 * [Configure Pyroscope to send profiling data](../../) 31 * Configure a client-side package to link traces and profiles: [Java](https://github.com/grafana/otel-profiling-java) 32 * [Configure the Tempo data source in Grafana or Grafana Cloud to discover linked traces and profiles](/docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source/) 33 34 ## Before you begin 35 36 Your applications must be instrumented for profiling and tracing before you can use span profiles. 37 38 * Profiling: Your application must be instrumented with Pyroscope's Java client SDK. Refer to the [Java](../../language-sdks/java/) guide for instructions. 39 * Tracing: Your application must be instrumented with OpenTelemetry traces. Refer to the [OpenTelemetry](https://opentelemetry.io/docs/languages/java/getting-started/) guide for instructions. 40 41 ## Configure the otel-profiling-java package 42 43 To start collecting Span Profiles for your Java application, you need to include [otel-profiling-java](https://github.com/pyroscope-io/otel-profiling-java) as an extension 44 for the [OTel Java agent](https://opentelemetry.io/docs/zero-code/java/agent/). 45 46 Assuming you have this sample application Docker image: 47 48 ```Dockerfile 49 # [...] 50 51 EXPOSE 5000 52 53 CMD ["java", "-Dserver.port=5000", "-jar", "./my-app.jar" ] 54 ``` 55 56 By adding the OTel Java agent and the Pyroscope OTel Java Agent extension, you can enrich your profiles with span IDs. This makes it possible to query for span-specific profiling data in Grafana Tempo: 57 58 ```Dockerfile 59 # [...] 60 61 EXPOSE 5000 62 63 ## Add required libararies 64 ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.17.0/opentelemetry-javaagent.jar opentelemetry-javaagent.jar 65 ADD https://github.com/grafana/otel-profiling-java/releases/download/v1.0.4/pyroscope-otel.jar pyroscope-otel.jar 66 67 ENV PYROSCOPE_APPLICATION_NAME=my-app 68 ENV PYROSCOPE_FORMAT=jfr 69 ENV PYROSCOPE_PROFILING_INTERVAL=10ms 70 ENV PYROSCOPE_PROFILER_EVENT=itimer 71 ENV PYROSCOPE_PROFILER_LOCK=10ms 72 ENV PYROSCOPE_PROFILER_ALLOC=512k 73 ENV PYROSCOPE_UPLOAD_INTERVAL=15s 74 ENV OTEL_JAVAAGENT_EXTENSIONS=./pyroscope-otel.jar 75 ENV OTEL_PYROSCOPE_ADD_PROFILE_URL=false 76 ENV OTEL_PYROSCOPE_ADD_PROFILE_BASELINE_URL=false 77 ENV OTEL_PYROSCOPE_START_PROFILING=true 78 79 ## Useful for debugging 80 # ENV PYROSCOPE_LOG_LEVEL=debug 81 82 ## Those environment variables need to be overwritten at runtime, if you are using Grafana Cloud 83 ENV PYROSCOPE_SERVER_ADDRESS=http://localhost:4040 84 # ENV PYROSCOPE_BASIC_AUTH_USER=123 ## Grafana Cloud Username 85 # ENV PYROSCOPE_BASIC_AUTH_PASSWORD=glc_secret ## Grafana Cloud Password / API Token 86 87 ## Add the opentelemetry java agent 88 CMD ["java", "-Dserver.port=5000", "-javaagent:./opentelemetry-javaagent.jar", "-jar", "./my-app.jar" ] 89 ``` 90 91 ### Available configuration options 92 93 | Flag | Description | Default | 94 |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| 95 | `otel.pyroscope.start.profiling` | Boolean flag to start PyroscopeAgent. Set to false if you want to start the PyroscopeAgent manually. | `true` | 96 | `otel.pyroscope.root.span.only` | Boolean flag. When enabled, the tracer will annotate only the first span created locally (the root span), but the profile will include samples of all the nested spans. This may be helpful in case if the trace consists of multiple spans shorter than 10ms and profiler can't collect and annotate samples properly. | `true` | 97 | `otel.pyroscope.add.span.name` | Boolean flag. Controls whether the span name added to profile labels. | `true` | 98 99 ## View the span profiles in Grafana Tempo 100 101 To view the span profiles in Grafana Tempo, you need to have a Grafana instance running and a data source configured to link trace spans and profiles. 102 103 Refer to the [data source configuration documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/configure-tempo-data-source/) to see how to configure the visualization to link trace spans with profiles. 104 105 To use a simple configuration, follow these steps: 106 107 1. Select a Pyroscope data source from the Data source drop-down. 108 109 2. Optional: Choose any tags to use in the query. If left blank, the default values of `service.name` and `service.namespace` are used. 110 111 The tags you configure must be present in the spans attributes or resources for a trace to profiles span link to appear. You can optionally configure a new name for the tag. This is useful for example if the tag has dots in the name and the target data source doesn't allow using dots in labels. In that case you can for example remap service.name to service_name. 112 113 3. Select one or more profile types to use in the query. Select the drop-down and choose options from the menu. 114 115 The profile type or app must be selected for the query to be valid. Grafana doesn't show any data if the profile type or app isn’t selected when a query runs. 116 117  118 119 ## Examples 120 121 Check out the [examples](https://github.com/grafana/pyroscope/tree/main/examples/tracing/java) directory for a complete demo application that shows tracing integration features.