From f4cec5d93dfbb8b49940e569520655ef1a47731b Mon Sep 17 00:00:00 2001 From: Aleksandar Petrov <8142643+aleks-p@users.noreply.github.com> Date: Fri, 17 Jan 2025 15:11:27 -0400 Subject: [PATCH] docs: add missing Java profiling options (#3850) --- .../configure-client/language-sdks/java.md | 44 +++++++++++-------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/docs/sources/configure-client/language-sdks/java.md b/docs/sources/configure-client/language-sdks/java.md index aca44fd637..d725e3a22e 100644 --- a/docs/sources/configure-client/language-sdks/java.md +++ b/docs/sources/configure-client/language-sdks/java.md @@ -167,25 +167,31 @@ Property keys have the same names as environment variables, but are in lowercase The Java integration supports JFR format to be able to support multiple events (JFR is the only output format that supports [multiple events in `async-profiler`](https://github.com/jvm-profiling-tools/async-profiler#multiple-events)). There are several environment variables that define how multiple event configuration works: -| Flag | Description | -|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `PYROSCOPE_AGENT_ENABLED` | Enables the agent. The default is `true`. | -| `PYROSCOPE_FORMAT` | Sets the profiler output format. The default is `collapsed`, but in order to support multiple formats it must be set to `jfr`. | -| `PYROSCOPE_PROFILER_EVENT` | Sets the profiler event. With JFR format enabled, this event refers to one of the possible CPU profiling events: `itimer`, `cpu`, `wall`. The default is `itimer`. | -| `PYROSCOPE_PROFILER_ALLOC` | Sets the allocation threshold to register the events, in bytes (equivalent to `--alloc=` in `async-profiler`). The default value is `""` - empty string, which means that allocation profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 512k and adjusting it as needed. | -| `PYROSCOPE_PROFILER_LOCK` | Sets the lock threshold to register the events, in nanoseconds (equivalent to `--lock=` in `async-profiler`). The default value is `""` - empty string, which means that lock profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 10ms and adjusting it as needed. | -| `PYROSCOPE_CONFIGURATION_FILE` | Sets an additional properties configuration file. The default value is `pyroscope.properties`. | -| `PYROSCOPE_BASIC_AUTH_USER` | HTTP Basic authentication username. The default value is `""` - empty string, no authentication. | -| `PYROSCOPE_BASIC_AUTH_PASSWORD` | HTTP Basic authentication password. The default value is `""` - empty string, no authentication. | -| `PYROSCOPE_TENANT_ID` | pyroscope tenant ID, passed as X-Scope-OrgID http header. The default value is `""` - empty string, no tenant ID. | -| `PYROSCOPE_HTTP_HEADERS` | Extra HTTP headers in JSON format, for example: `{"X-Header": "Value"}`. The default value is `{}` - no extra headers. | -| `PYROSCOPE_LABELS` | Sets static labels in the form of comma separated `key=value` pairs. The default value is `""` - empty string, no labels. | -| `PYROSCOPE_LOG_LEVEL` | Determines the level of verbosity for Pyroscope's logger. Available options include `debug`, `info`, `warn`, and `error`. The default value is set to `info`. | -| `PYROSCOPE_PUSH_QUEUE_CAPACITY` | Specifies the size of the ingestion queue that temporarily stores profiling data in memory during network outages. The default value is set to 8. | -| `PYROSCOPE_INGEST_MAX_TRIES` | Sets the maximum number of times to retry an ingestion API call in the event of failure. A value of `-1` indicates that the retries will continue indefinitely. The default value is set to `8`. | -| `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR` | Sets the level of GZIP compression applied to uploaded JFR files. This option accepts values of `NO_COMPRESSION`, `BEST_SPEED`, `BEST_COMPRESSION`, and `DEFAULT_COMPRESSION`. | -| `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_LABELS` | Operates similarly to `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR`, but applies to the dynamic labels part. The default value is set to `BEST_SPEED`. | -| `PYROSCOPE_GC_BEFORE_DUMP` | A boolean value that executes a `System.gc()` command before dumping the profile when set to `true`. This option may be useful for live profiling, but is disabled by default. | +| Flag | Description | +|---------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `PYROSCOPE_AGENT_ENABLED` | Enables the agent. The default is `true`. | +| `PYROSCOPE_APPLICATION_NAME` | Sets the application name. If not provided, a generated name will be used. | +| `PYROSCOPE_PROFILING_INTERVAL` | Sets the profiling sampling interval for CPU profiling. The default is `10ms`. | +| `PYROSCOPE_FORMAT` | Sets the profiler output format. The default is `collapsed`, but in order to support multiple formats it must be set to `jfr`. | +| `PYROSCOPE_PROFILER_EVENT` | Sets the profiler event. With JFR format enabled, this event refers to one of the possible CPU profiling events: `itimer`, `cpu`, `wall`. The default is `itimer`. | +| `PYROSCOPE_PROFILER_ALLOC` | Sets the threshold to register allocation events, in bytes (equivalent to `--alloc=` in `async-profiler`). The default value is `""` - empty string, which means that allocation profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 512k and adjusting it as needed. | +| `PYROSCOPE_PROFILER_LOCK` | Sets the threshold to register lock events, in nanoseconds (equivalent to `--lock=` in `async-profiler`). The default value is `""` - empty string, which means that lock profiling is disabled. Setting it to `0` will register every event, causing significant CPU and network overhead, making it not suitable for production environments. We recommend setting a starting value of 10ms and adjusting it as needed. | +| `PYROSCOPE_UPLOAD_INTERVAL` | Sets the interval for uploading profiling data. The default is `10s`. | +| `PYROSCOPE_JAVA_STACK_DEPTH_MAX` | Sets the maximum stack depth. The default is `2048`. | +| `PYROSCOPE_SERVER_ADDRESS` | Address of the Pyroscope server. The default is `http://localhost:4040` | +| `PYROSCOPE_CONFIGURATION_FILE` | Sets an additional properties configuration file. The default value is `pyroscope.properties`. | +| `PYROSCOPE_BASIC_AUTH_USER` | HTTP Basic authentication username. The default value is `""` - empty string, no authentication. | +| `PYROSCOPE_BASIC_AUTH_PASSWORD` | HTTP Basic authentication password. The default value is `""` - empty string, no authentication. | +| `PYROSCOPE_TENANT_ID` | pyroscope tenant ID, passed as X-Scope-OrgID http header. The default value is `""` - empty string, no tenant ID. | +| `PYROSCOPE_HTTP_HEADERS` | Extra HTTP headers in JSON format, for example: `{"X-Header": "Value"}`. The default value is `{}` - no extra headers. | +| `PYROSCOPE_LABELS` | Sets static labels in the form of comma separated `key=value` pairs. The default value is `""` - empty string, no labels. | +| `PYROSCOPE_LOG_LEVEL` | Determines the level of verbosity for Pyroscope's logger. Available options include `debug`, `info`, `warn`, and `error`. The default value is set to `info`. | +| `PYROSCOPE_PUSH_QUEUE_CAPACITY` | Specifies the size of the ingestion queue that temporarily stores profiling data in memory during network outages. The default value is set to 8. | +| `PYROSCOPE_INGEST_MAX_TRIES` | Sets the maximum number of times to retry an ingestion API call in the event of failure. A value of `-1` indicates that the retries will continue indefinitely. The default value is set to `8`. | +| `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR` | Sets the level of GZIP compression applied to uploaded JFR files. This option accepts values of `NO_COMPRESSION`, `BEST_SPEED`, `BEST_COMPRESSION`, and `DEFAULT_COMPRESSION`. | +| `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_LABELS` | Operates similarly to `PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR`, but applies to the dynamic labels part. The default value is set to `BEST_SPEED`. | +| `PYROSCOPE_ALLOC_LIVE` | Retain allocation samples with live objects only (objects that have not been collected by the end of profiling session). Useful for finding Java heap memory leaks. The default value is `false` | +| `PYROSCOPE_GC_BEFORE_DUMP` | A boolean value that executes a `System.gc()` command before dumping the profile when set to `true`. This option may be useful for live profiling, but is disabled by default. | ## Send data to Pyroscope OSS or Grafana Cloud Profiles