From d6a0b7e3db0bd0802b50fcfc1f52e926873c358e Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Aug 2023 12:37:39 -0500 Subject: [PATCH 1/4] shorten apm agent page IDs --- ...apm-send-traces-to-elastic-android-api.mdx | 2 +- ...nd-traces-to-elastic-android-configure.mdx | 2 +- ...-traces-to-elastic-android-get-started.mdx | 2 +- ...send-traces-to-elastic-android-install.mdx | 2 +- ...-to-elastic-android-performance-tuning.mdx | 2 +- ...elastic-android-supported-technologies.mdx | 2 +- ...nce-apm-send-traces-to-elastic-android.mdx | 2 +- ...d-traces-to-elastic-elastic-apm-agents.mdx | 2 +- ...ance-apm-send-traces-to-elastic-go-api.mdx | 2 +- ...pm-send-traces-to-elastic-go-configure.mdx | 2 +- ...-send-traces-to-elastic-go-get-started.mdx | 2 +- ...-apm-send-traces-to-elastic-go-install.mdx | 2 +- ...races-to-elastic-go-performance-tuning.mdx | 2 +- ...s-to-elastic-go-supported-technologies.mdx | 2 +- ...formance-apm-send-traces-to-elastic-go.mdx | 2 +- ...nce-apm-send-traces-to-elastic-ios-api.mdx | 2 +- ...m-send-traces-to-elastic-ios-configure.mdx | 2 +- ...send-traces-to-elastic-ios-get-started.mdx | 2 +- ...apm-send-traces-to-elastic-ios-install.mdx | 2 +- ...aces-to-elastic-ios-performance-tuning.mdx | 2 +- ...-to-elastic-ios-supported-technologies.mdx | 2 +- ...ormance-apm-send-traces-to-elastic-ios.mdx | 2 +- ...ce-apm-send-traces-to-elastic-java-api.mdx | 2 +- ...-send-traces-to-elastic-java-configure.mdx | 2 +- ...end-traces-to-elastic-java-get-started.mdx | 2 +- ...pm-send-traces-to-elastic-java-install.mdx | 2 +- ...ces-to-elastic-java-performance-tuning.mdx | 2 +- ...to-elastic-java-supported-technologies.mdx | 2 +- ...rmance-apm-send-traces-to-elastic-java.mdx | 2 +- ...nce-apm-send-traces-to-elastic-net-api.mdx | 2 +- ...m-send-traces-to-elastic-net-configure.mdx | 2 +- ...send-traces-to-elastic-net-get-started.mdx | 2 +- ...apm-send-traces-to-elastic-net-install.mdx | 2 +- ...aces-to-elastic-net-performance-tuning.mdx | 2 +- ...-to-elastic-net-supported-technologies.mdx | 2 +- ...ormance-apm-send-traces-to-elastic-net.mdx | 2 +- ...-apm-send-traces-to-elastic-nodejs-api.mdx | 2 +- ...end-traces-to-elastic-nodejs-configure.mdx | 2 +- ...d-traces-to-elastic-nodejs-get-started.mdx | 2 +- ...-send-traces-to-elastic-nodejs-install.mdx | 2 +- ...s-to-elastic-nodejs-performance-tuning.mdx | 2 +- ...-elastic-nodejs-supported-technologies.mdx | 2 +- ...ance-apm-send-traces-to-elastic-nodejs.mdx | 2 +- ...-elastic-opentelemetry-collect-metrics.mdx | 2 +- ...s-to-elastic-opentelemetry-limitations.mdx | 2 +- ...lemetry-apisdk-with-elastic-apm-agents.mdx | 2 +- ...telemetry-opentelemetry-native-support.mdx | 2 +- ...telemetry-other-execution-environments.mdx | 2 +- ...stic-opentelemetry-resource-attributes.mdx | 2 +- ...m-send-traces-to-elastic-opentelemetry.mdx | 2 +- ...nce-apm-send-traces-to-elastic-php-api.mdx | 2 +- ...m-send-traces-to-elastic-php-configure.mdx | 2 +- ...send-traces-to-elastic-php-get-started.mdx | 2 +- ...apm-send-traces-to-elastic-php-install.mdx | 2 +- ...aces-to-elastic-php-performance-tuning.mdx | 2 +- ...-to-elastic-php-supported-technologies.mdx | 2 +- ...ormance-apm-send-traces-to-elastic-php.mdx | 2 +- ...-apm-send-traces-to-elastic-python-api.mdx | 2 +- ...end-traces-to-elastic-python-configure.mdx | 2 +- ...d-traces-to-elastic-python-get-started.mdx | 2 +- ...-send-traces-to-elastic-python-install.mdx | 2 +- ...s-to-elastic-python-performance-tuning.mdx | 2 +- ...-elastic-python-supported-technologies.mdx | 2 +- ...ance-apm-send-traces-to-elastic-python.mdx | 2 +- ...ce-apm-send-traces-to-elastic-ruby-api.mdx | 2 +- ...-send-traces-to-elastic-ruby-configure.mdx | 2 +- ...end-traces-to-elastic-ruby-get-started.mdx | 2 +- ...pm-send-traces-to-elastic-ruby-install.mdx | 2 +- ...ces-to-elastic-ruby-performance-tuning.mdx | 2 +- ...to-elastic-ruby-supported-technologies.mdx | 2 +- ...rmance-apm-send-traces-to-elastic-ruby.mdx | 2 +- ...nce-apm-send-traces-to-elastic-rum-api.mdx | 2 +- ...m-send-traces-to-elastic-rum-configure.mdx | 2 +- ...send-traces-to-elastic-rum-get-started.mdx | 2 +- ...apm-send-traces-to-elastic-rum-install.mdx | 2 +- ...aces-to-elastic-rum-performance-tuning.mdx | 2 +- ...-to-elastic-rum-supported-technologies.mdx | 2 +- ...ormance-apm-send-traces-to-elastic-rum.mdx | 2 +- serverless-observability.docnav.json | 156 +++++++++--------- 79 files changed, 156 insertions(+), 156 deletions(-) diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx index 992167b25f..1d7cf98c40 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidApi +id: serverlessObservabilityApmAgentsAndroidApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx index ac47b96664..522f63cfdf 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidConfigure +id: serverlessObservabilityApmAgentsAndroidConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx index 883d5f996f..ce9934d34c 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidGetStarted +id: serverlessObservabilityApmAgentsAndroidGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx index 1312097c6f..380fa061bd 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidInstall +id: serverlessObservabilityApmAgentsAndroidInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx index 5c8d012a96..267e8757cd 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidPerformanceTuning +id: serverlessObservabilityApmAgentsAndroidPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx index e67ec06b2a..21f86a4f8b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidSupportedTechnologies +id: serverlessObservabilityApmAgentsAndroidSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx index 1b966bab13..5e1bed5067 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroid +id: serverlessObservabilityApmAgentsAndroid slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android title: Android # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx index 9b590141cc..52cb544fb7 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticElasticApmAgents +id: serverlessObservabilityApmAgents slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents title: Elastic APM agents # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx index 5e11be9dc3..c493472f5b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoApi +id: serverlessObservabilityApmAgentsGoApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx index 77125d8037..dbab74bfaf 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoConfigure +id: serverlessObservabilityApmAgentsGoConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx index e456e6158f..a14b2a3c61 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoGetStarted +id: serverlessObservabilityApmAgentsGoGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx index 7bb6c4f9a8..bfa4c67962 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoInstall +id: serverlessObservabilityApmAgentsGoInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx index e8ea372188..442454dcdd 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoPerformanceTuning +id: serverlessObservabilityApmAgentsGoPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx index 550383268a..79523bf325 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoSupportedTechnologies +id: serverlessObservabilityApmAgentsGoSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx index 2328d1215d..f32045236e 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGo +id: serverlessObservabilityApmAgentsGo slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go title: Go # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx index 4e38701ff1..ea9e00232d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosApi +id: serverlessObservabilityApmAgentsIosApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx index 3fc1af70a3..c335a2f15f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosConfigure +id: serverlessObservabilityApmAgentsIosConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx index 387e30af6b..8042237379 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosGetStarted +id: serverlessObservabilityApmAgentsIosGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx index d1baba8e92..da41437d47 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosInstall +id: serverlessObservabilityApmAgentsIosInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx index 3cd27e644e..13f1364cf3 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosPerformanceTuning +id: serverlessObservabilityApmAgentsIosPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx index c969e4c296..e58511fe7a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosSupportedTechnologies +id: serverlessObservabilityApmAgentsIosSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx index fee3e91826..b4255419aa 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIos +id: serverlessObservabilityApmAgentsIos slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios title: iOS # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx index a923742c03..fbdfd12a6e 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaApi +id: serverlessObservabilityApmAgentsJavaApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx index 2ad49b59c1..33fec86e04 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaConfigure +id: serverlessObservabilityApmAgentsJavaConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx index 4e70caf462..4ccbdb1356 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaGetStarted +id: serverlessObservabilityApmAgentsJavaGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx index c0a9545026..4f6d535795 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaInstall +id: serverlessObservabilityApmAgentsJavaInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx index 15544e7e95..96dc891c2b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaPerformanceTuning +id: serverlessObservabilityApmAgentsJavaPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx index 81f325295b..ec6efbe71a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaSupportedTechnologies +id: serverlessObservabilityApmAgentsJavaSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx index a16427c224..fab4423202 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJava +id: serverlessObservabilityApmAgentsJava slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java title: Java # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx index 2e4171e13b..d498d2e489 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetApi +id: serverlessObservabilityApmAgentsNetApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx index 061588cd57..b524193357 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetConfigure +id: serverlessObservabilityApmAgentsNetConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx index 0146d90559..8438fa2c3f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetGetStarted +id: serverlessObservabilityApmAgentsNetGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx index 7bcfeb14a0..010df13720 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetInstall +id: serverlessObservabilityApmAgentsNetInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx index 47eca4bb5a..3dc3a145f0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetPerformanceTuning +id: serverlessObservabilityApmAgentsNetPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx index f033de9f5a..27d7b502ff 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetSupportedTechnologies +id: serverlessObservabilityApmAgentsNetSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx index e1535dbc79..1386b0c6ce 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNet +id: serverlessObservabilityApmAgentsNet slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net title: .NET # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx index 7ba10941fd..088857cc4a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsApi +id: serverlessObservabilityApmAgentsNodejsApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx index 28dcf23b6e..69ddf36747 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsConfigure +id: serverlessObservabilityApmAgentsNodejsConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx index 81bd655a91..79d58b20d2 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsGetStarted +id: serverlessObservabilityApmAgentsNodejsGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx index f4a8a3905b..0c424b440f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsInstall +id: serverlessObservabilityApmAgentsNodejsInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx index 33e0d09668..2d071ee334 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsPerformanceTuning +id: serverlessObservabilityApmAgentsNodejsPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx index bd2d5989c1..9ceed95e90 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsSupportedTechnologies +id: serverlessObservabilityApmAgentsNodejsSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx index d0261fc6ba..fd9aadf076 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejs +id: serverlessObservabilityApmAgentsNodejs slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs title: Node.js # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx index 8c0a9391d1..e908d3e62d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryCollectMetrics +id: serverlessObservabilityApmAgentsOtelCollectMetrics slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics title: Collect metrics # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx index 08b14b9e9a..10d1f49a9a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryLimitations +id: serverlessObservabilityApmAgentsOtelLimitations slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations title: Limitations # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx index 818bfdff74..a1249f4d15 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOpentelemetryApisdkWithElasticApmAgents +id: serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents title: OpenTelemetry API/SDK with Elastic APM agents # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx index 487a5e6c91..c017d16548 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOpentelemetryNativeSupport +id: serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support title: OpenTelemetry native support # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx index c2bf6c4520..31e08d00d7 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOtherExecutionEnvironments +id: serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments title: Other execution environments # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx index cd4f32c111..15b6bc35b4 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryResourceAttributes +id: serverlessObservabilityApmAgentsOtelResourceAttributes slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes title: Resource attributes # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx index 8b62d32e7a..423eae47b6 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetry +id: serverlessObservabilityApmAgentsOtel slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry title: OpenTelemetry # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx index ebd7de5252..cbff9a50de 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpApi +id: serverlessObservabilityApmAgentsPhpApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx index e1bfa2944c..9cbdb8f040 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpConfigure +id: serverlessObservabilityApmAgentsPhpConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx index ba49c57061..c528fc8e67 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpGetStarted +id: serverlessObservabilityApmAgentsPhpGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx index bc7cca6b66..e886736737 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpInstall +id: serverlessObservabilityApmAgentsPhpInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx index f85a24429a..91b56c2259 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpPerformanceTuning +id: serverlessObservabilityApmAgentsPhpPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx index 1f17fd7d31..905e4ae231 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpSupportedTechnologies +id: serverlessObservabilityApmAgentsPhpSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx index 4ab3cc512d..8b76b416e1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhp +id: serverlessObservabilityApmAgentsPhp slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php title: PHP # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx index f7290889b1..8705e9f8d9 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonApi +id: serverlessObservabilityApmAgentsPythonApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx index 89ca6aa1ca..668569ebb2 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonConfigure +id: serverlessObservabilityApmAgentsPythonConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx index f4e91fda16..ac036c7371 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonGetStarted +id: serverlessObservabilityApmAgentsPythonGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx index 000eb0f5ac..4b0681b722 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonInstall +id: serverlessObservabilityApmAgentsPythonInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx index 944c9d09c7..1a857d0fd6 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonPerformanceTuning +id: serverlessObservabilityApmAgentsPythonPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx index f683edc483..56488d5abd 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonSupportedTechnologies +id: serverlessObservabilityApmAgentsPythonSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx index aaa2a72f3a..91fe3e8c81 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPython +id: serverlessObservabilityApmAgentsPython slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python title: Python # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx index 8050a2ccee..b720922552 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyApi +id: serverlessObservabilityApmAgentsRubyApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx index c8d78d9433..0d4416124c 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyConfigure +id: serverlessObservabilityApmAgentsRubyConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx index c96fd0194e..fa3e2268a8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyGetStarted +id: serverlessObservabilityApmAgentsRubyGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx index f3abbbe743..66a887e6fa 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyInstall +id: serverlessObservabilityApmAgentsRubyInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx index 1be70381f4..30576f574b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyPerformanceTuning +id: serverlessObservabilityApmAgentsRubyPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx index 6b649a50d1..a76daf1bde 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubySupportedTechnologies +id: serverlessObservabilityApmAgentsRubySupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx index 56e186c548..36f0f944c0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRuby +id: serverlessObservabilityApmAgentsRuby slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby title: Ruby # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx index 1ab4d8dc21..bb31c84e6a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumApi +id: serverlessObservabilityApmAgentsRumApi slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-api title: API # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx index 18892df2ea..173de43b62 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumConfigure +id: serverlessObservabilityApmAgentsRumConfigure slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-configure title: Configure # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx index 64bd2f6f2c..eda18e85da 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumGetStarted +id: serverlessObservabilityApmAgentsRumGetStarted slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started title: Get started # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx index adfa2ae7ad..9cd1c89d49 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumInstall +id: serverlessObservabilityApmAgentsRumInstall slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-install title: Install # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx index e5d393a110..3b99ddf95a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumPerformanceTuning +id: serverlessObservabilityApmAgentsRumPerformanceTuning slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning title: Performance tuning # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx index 36d790cfe5..f18bcb1212 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumSupportedTechnologies +id: serverlessObservabilityApmAgentsRumSupportedTechnologies slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies title: Supported technologies # description: Description to be written diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx index 074b635d26..0f5ffabe14 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx @@ -1,5 +1,5 @@ --- -id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRum +id: serverlessObservabilityApmAgentsRum slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum title: RUM # description: Description to be written diff --git a/serverless-observability.docnav.json b/serverless-observability.docnav.json index 0e9952b9fe..5b5a0d2fbf 100644 --- a/serverless-observability.docnav.json +++ b/serverless-observability.docnav.json @@ -68,258 +68,258 @@ "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElastic", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticElasticApmAgents" + "id": "serverlessObservabilityApmAgents" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroid", + "id": "serverlessObservabilityApmAgentsAndroid", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidGetStarted" + "id": "serverlessObservabilityApmAgentsAndroidGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsAndroidSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidInstall" + "id": "serverlessObservabilityApmAgentsAndroidInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidConfigure" + "id": "serverlessObservabilityApmAgentsAndroidConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidApi" + "id": "serverlessObservabilityApmAgentsAndroidApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAndroidPerformanceTuning" + "id": "serverlessObservabilityApmAgentsAndroidPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGo", + "id": "serverlessObservabilityApmAgentsGo", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoGetStarted" + "id": "serverlessObservabilityApmAgentsGoGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsGoSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoInstall" + "id": "serverlessObservabilityApmAgentsGoInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoConfigure" + "id": "serverlessObservabilityApmAgentsGoConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoApi" + "id": "serverlessObservabilityApmAgentsGoApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticGoPerformanceTuning" + "id": "serverlessObservabilityApmAgentsGoPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIos", + "id": "serverlessObservabilityApmAgentsIos", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosGetStarted" + "id": "serverlessObservabilityApmAgentsIosGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsIosSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosInstall" + "id": "serverlessObservabilityApmAgentsIosInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosConfigure" + "id": "serverlessObservabilityApmAgentsIosConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosApi" + "id": "serverlessObservabilityApmAgentsIosApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticIosPerformanceTuning" + "id": "serverlessObservabilityApmAgentsIosPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJava", + "id": "serverlessObservabilityApmAgentsJava", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaGetStarted" + "id": "serverlessObservabilityApmAgentsJavaGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsJavaSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaInstall" + "id": "serverlessObservabilityApmAgentsJavaInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaConfigure" + "id": "serverlessObservabilityApmAgentsJavaConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaApi" + "id": "serverlessObservabilityApmAgentsJavaApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJavaPerformanceTuning" + "id": "serverlessObservabilityApmAgentsJavaPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNet", + "id": "serverlessObservabilityApmAgentsNet", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetGetStarted" + "id": "serverlessObservabilityApmAgentsNetGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsNetSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetInstall" + "id": "serverlessObservabilityApmAgentsNetInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetConfigure" + "id": "serverlessObservabilityApmAgentsNetConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetApi" + "id": "serverlessObservabilityApmAgentsNetApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNetPerformanceTuning" + "id": "serverlessObservabilityApmAgentsNetPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejs", + "id": "serverlessObservabilityApmAgentsNodejs", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsGetStarted" + "id": "serverlessObservabilityApmAgentsNodejsGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsNodejsSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsInstall" + "id": "serverlessObservabilityApmAgentsNodejsInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsConfigure" + "id": "serverlessObservabilityApmAgentsNodejsConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsApi" + "id": "serverlessObservabilityApmAgentsNodejsApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticNodejsPerformanceTuning" + "id": "serverlessObservabilityApmAgentsNodejsPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhp", + "id": "serverlessObservabilityApmAgentsPhp", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpGetStarted" + "id": "serverlessObservabilityApmAgentsPhpGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsPhpSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpInstall" + "id": "serverlessObservabilityApmAgentsPhpInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpConfigure" + "id": "serverlessObservabilityApmAgentsPhpConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpApi" + "id": "serverlessObservabilityApmAgentsPhpApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPhpPerformanceTuning" + "id": "serverlessObservabilityApmAgentsPhpPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPython", + "id": "serverlessObservabilityApmAgentsPython", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonGetStarted" + "id": "serverlessObservabilityApmAgentsPythonGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsPythonSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonInstall" + "id": "serverlessObservabilityApmAgentsPythonInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonConfigure" + "id": "serverlessObservabilityApmAgentsPythonConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonApi" + "id": "serverlessObservabilityApmAgentsPythonApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticPythonPerformanceTuning" + "id": "serverlessObservabilityApmAgentsPythonPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRuby", + "id": "serverlessObservabilityApmAgentsRuby", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyGetStarted" + "id": "serverlessObservabilityApmAgentsRubyGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubySupportedTechnologies" + "id": "serverlessObservabilityApmAgentsRubySupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyInstall" + "id": "serverlessObservabilityApmAgentsRubyInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyConfigure" + "id": "serverlessObservabilityApmAgentsRubyConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyApi" + "id": "serverlessObservabilityApmAgentsRubyApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRubyPerformanceTuning" + "id": "serverlessObservabilityApmAgentsRubyPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRum", + "id": "serverlessObservabilityApmAgentsRum", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumGetStarted" + "id": "serverlessObservabilityApmAgentsRumGetStarted" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsRumSupportedTechnologies" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumInstall" + "id": "serverlessObservabilityApmAgentsRumInstall" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumConfigure" + "id": "serverlessObservabilityApmAgentsRumConfigure" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumApi" + "id": "serverlessObservabilityApmAgentsRumApi" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticRumPerformanceTuning" + "id": "serverlessObservabilityApmAgentsRumPerformanceTuning" } ] }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetry", + "id": "serverlessObservabilityApmAgentsOtel", "items": [ { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOpentelemetryApisdkWithElasticApmAgents" + "id": "serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOpentelemetryNativeSupport" + "id": "serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryOtherExecutionEnvironments" + "id": "serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryCollectMetrics" + "id": "serverlessObservabilityApmAgentsOtelCollectMetrics" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryLimitations" + "id": "serverlessObservabilityApmAgentsOtelLimitations" }, { - "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticOpentelemetryResourceAttributes" + "id": "serverlessObservabilityApmAgentsOtelResourceAttributes" } ] }, From f343eba3e277aa2828b237661e9dde65f2435439 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Aug 2023 17:03:05 -0500 Subject: [PATCH 2/4] copy first draft of apm agents docs from sandbox --- ...apm-send-traces-to-elastic-android-api.mdx | 2 + ...nd-traces-to-elastic-android-configure.mdx | 296 ++++ ...-traces-to-elastic-android-get-started.mdx | 123 ++ ...send-traces-to-elastic-android-install.mdx | 2 + ...-to-elastic-android-performance-tuning.mdx | 2 + ...elastic-android-supported-technologies.mdx | 68 + ...nce-apm-send-traces-to-elastic-android.mdx | 30 + ...traces-to-elastic-aws-lambda-functions.mdx | 2 + ...d-traces-to-elastic-elastic-apm-agents.mdx | 2 + ...ance-apm-send-traces-to-elastic-go-api.mdx | 598 ++++++++ ...pm-send-traces-to-elastic-go-configure.mdx | 698 +++++++++ ...-send-traces-to-elastic-go-get-started.mdx | 52 + ...-apm-send-traces-to-elastic-go-install.mdx | 2 + ...races-to-elastic-go-performance-tuning.mdx | 2 + ...s-to-elastic-go-supported-technologies.mdx | 320 +++++ ...formance-apm-send-traces-to-elastic-go.mdx | 44 + ...nce-apm-send-traces-to-elastic-ios-api.mdx | 2 + ...m-send-traces-to-elastic-ios-configure.mdx | 66 + ...send-traces-to-elastic-ios-get-started.mdx | 262 ++++ ...apm-send-traces-to-elastic-ios-install.mdx | 2 + ...aces-to-elastic-ios-performance-tuning.mdx | 2 + ...-to-elastic-ios-supported-technologies.mdx | 9 + ...ormance-apm-send-traces-to-elastic-ios.mdx | 44 + ...ance-apm-send-traces-to-elastic-jaeger.mdx | 2 + ...ce-apm-send-traces-to-elastic-java-api.mdx | 55 + ...-send-traces-to-elastic-java-configure.mdx | 154 ++ ...end-traces-to-elastic-java-get-started.mdx | 114 ++ ...pm-send-traces-to-elastic-java-install.mdx | 2 + ...ces-to-elastic-java-performance-tuning.mdx | 156 ++ ...to-elastic-java-supported-technologies.mdx | 643 +++++++++ ...rmance-apm-send-traces-to-elastic-java.mdx | 48 + ...nce-apm-send-traces-to-elastic-net-api.mdx | 897 ++++++++++++ ...m-send-traces-to-elastic-net-configure.mdx | 48 + ...send-traces-to-elastic-net-get-started.mdx | 90 ++ ...apm-send-traces-to-elastic-net-install.mdx | 2 + ...aces-to-elastic-net-performance-tuning.mdx | 89 ++ ...-to-elastic-net-supported-technologies.mdx | 490 +++++++ ...ormance-apm-send-traces-to-elastic-net.mdx | 43 + ...-apm-send-traces-to-elastic-nodejs-api.mdx | 989 +++++++++++++ ...end-traces-to-elastic-nodejs-configure.mdx | 22 + ...d-traces-to-elastic-nodejs-get-started.mdx | 151 ++ ...-send-traces-to-elastic-nodejs-install.mdx | 2 + ...s-to-elastic-nodejs-performance-tuning.mdx | 169 +++ ...-elastic-nodejs-supported-technologies.mdx | 176 +++ ...ance-apm-send-traces-to-elastic-nodejs.mdx | 41 + ...-elastic-opentelemetry-collect-metrics.mdx | 2 + ...s-to-elastic-opentelemetry-limitations.mdx | 2 + ...lemetry-apisdk-with-elastic-apm-agents.mdx | 2 + ...telemetry-opentelemetry-native-support.mdx | 2 + ...telemetry-other-execution-environments.mdx | 2 + ...stic-opentelemetry-resource-attributes.mdx | 2 + ...m-send-traces-to-elastic-opentelemetry.mdx | 2 + ...nce-apm-send-traces-to-elastic-php-api.mdx | 654 +++++++++ ...m-send-traces-to-elastic-php-configure.mdx | 583 ++++++++ ...send-traces-to-elastic-php-get-started.mdx | 91 ++ ...apm-send-traces-to-elastic-php-install.mdx | 2 + ...aces-to-elastic-php-performance-tuning.mdx | 2 + ...-to-elastic-php-supported-technologies.mdx | 76 + ...ormance-apm-send-traces-to-elastic-php.mdx | 27 + ...-apm-send-traces-to-elastic-python-api.mdx | 546 +++++++ ...end-traces-to-elastic-python-configure.mdx | 1268 +++++++++++++++++ ...d-traces-to-elastic-python-get-started.mdx | 121 ++ ...-send-traces-to-elastic-python-install.mdx | 2 + ...s-to-elastic-python-performance-tuning.mdx | 114 ++ ...-elastic-python-supported-technologies.mdx | 670 +++++++++ ...ance-apm-send-traces-to-elastic-python.mdx | 33 + ...ce-apm-send-traces-to-elastic-ruby-api.mdx | 481 +++++++ ...-send-traces-to-elastic-ruby-configure.mdx | 850 +++++++++++ ...end-traces-to-elastic-ruby-get-started.mdx | 99 ++ ...pm-send-traces-to-elastic-ruby-install.mdx | 2 + ...ces-to-elastic-ruby-performance-tuning.mdx | 108 ++ ...to-elastic-ruby-supported-technologies.mdx | 159 +++ ...rmance-apm-send-traces-to-elastic-ruby.mdx | 42 + ...nce-apm-send-traces-to-elastic-rum-api.mdx | 287 ++++ ...m-send-traces-to-elastic-rum-configure.mdx | 418 ++++++ ...send-traces-to-elastic-rum-get-started.mdx | 46 + ...apm-send-traces-to-elastic-rum-install.mdx | 2 + ...aces-to-elastic-rum-performance-tuning.mdx | 60 + ...-to-elastic-rum-supported-technologies.mdx | 134 ++ ...ormance-apm-send-traces-to-elastic-rum.mdx | 39 + serverless-observability.docnav.json | 335 ++++- 81 files changed, 14202 insertions(+), 76 deletions(-) diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx index 1d7cf98c40..13d1e5ab24 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx @@ -5,3 +5,5 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx index 522f63cfdf..edc210d296 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx @@ -5,3 +5,299 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + + +
+ +## Gradle configuration + +Configure your application at compile time within your application's `build.gradle` file: + +```groovy +// Android app's build.gradle file +plugins { + //... + id "co.elastic.apm.android" version "[latest_version]" [^1] +} + +elasticApm { + // Minimal configuration + serverUrl = "https://your.elastic.server" + + // Optional + serviceName = "your app name" [^2] + serviceVersion = "0.0.0" [^3] + apiKey = "your server api key" [^4] + secretToken = "your server auth token" [^5] +} +``` +[^1]: You can find the latest version in the [Gradle plugin portal](https://plugins.gradle.org/plugin/co.elastic.apm.android). +[^2]: Defaults to your `android.defaultConfig.applicationId` value. +[^3]: Defaults to your `android.defaultConfig.versionName` value. +[^4]: Defaults to null. +More info on API Keys [here](((ref))/security-api-create-api-key.html). +[^5]: Defaults to null. + + +When both `secretToken` and `apiKey` are provided, apiKey has priority and secretToken is ignored. + + +All of the values provided in the Gradle configuration can be overridden with the following environment variables: + +| Config | Associated Environment variable | +|---|---| +| serviceName | `ELASTIC_APM_SERVICE_NAME` | +| serviceVersion | `ELASTIC_APM_SERVICE_VERSION` | +| serverUrl | `ELASTIC_APM_SERVER_URL` | +| apiKey | `ELASTIC_APM_API_KEY` | +| secretToken | `ELASTIC_APM_SECRET_TOKEN` | + +## Runtime configuration + +The runtime configuration is provided within your [Application](https://developer.android.com/reference/android/app/Application) class when initializing the Elastic agent. +This configuration overrides any previously-set compile time configuration. + +Runtime configuration works by providing your own instance of the `ElasticApmConfiguration` class as shown below: + +```java +// Application class + +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build()); + } +} +``` + +
+ +### APM Server connectivity + +The APM Server connectivity parameters can be provided at compile time, either by using the Gradle DSL configuration or by providing the APM Server connectivity-related environment variables as mentioned above. +Later on, when the app is running, the connectivity parameters can be overridden by providing a custom `Connectivity` instance when initializing the Elastic agent. + +Once you've created your `Connectivity` instance, you can set it into the agent's initialization as show below: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + Connectivity myCustomConnectivity = Connectivity.simple(/*params*/); + ElasticApmAgent.initialize(this, myCustomConnectivity); + + // Optionally if you also define a custom configuration: + // ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build(), myCustomConnectivity); + } +} +``` + +
+ +### Application ID configuration + +You can provide your application name, version, and environment dynamically when building your `ElasticApmConfiguration` instance as shown below: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + ElasticApmConfiguration configuration = ElasticApmConfiguration.builder() + .setServiceName("my-custom-name") + .setServiceVersion("1.0.0") + .setDeploymentEnvironment("debug") + .build(); + ElasticApmAgent.initialize(this, configuration); + } +} +``` + +### Signal filtering + +You can provide your own filters to specify which spans, logs, and metrics are allowed to be exported to the backend. +With this tool, you could essentially turn some of these signals (or all) on and off at runtime depending on your own business logic. + +In order to do so, you need to provide your own filters for each signal in the agent configuration as shown below: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + ElasticApmConfiguration configuration = ElasticApmConfiguration.builder() + .addLogFilter(new LogFilter(){/*...*/}) + .addMetricFilter(new MetricFilter(){/*...*/}) +// .addMetricFilter(new MetricFilter(){/*...*/}) You can add multiple filters per signal. + .addSpanFilter(new SpanFilter() { + @Override + public boolean shouldInclude(ReadableSpan readableSpan) { + if (thisSpanIsAllowedToContinue(readableSpan)) { + return true; + } + return false; + } + }) + .build(); + ElasticApmAgent.initialize(this, configuration); + } +} +``` + +Each filter will contain a `shouldInclude` function which provides the signal item to be evaluated. +This function must return a boolean value--`true` when the provided item is allowed to continue or `false` when it must be discarded. + +You can add multiple filters per signal which will be iterated over (in the order they were added) until all the filters are checked or until one of them decides to discard the signal item provided. + +### Automatic instrumentation enabling/disabling + +The agent provides automatic instrumentation for its Supported technologies which are all enabled by default. +You can choose which ones to keep enabled, as well as and disabling those you don't need, at runtime, like so: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + + // When building an InstrumentationConfiguration object using `InstrumentationConfiguration.builder()` + // all of the instrumentations are disabled by default, so you only need to enable the ones you need. + InstrumentationConfiguration instrumentations = InstrumentationConfiguration.builder() + .enableHttpTracing(true) + .build(); + ElasticApmConfiguration configuration = ElasticApmConfiguration.builder() + .setInstrumentationConfiguration(instrumentations) + .build(); + ElasticApmAgent.initialize(this, configuration); + } +} +``` + + +When building an InstrumentationConfiguration object using `InstrumentationConfiguration.builder()`, all instrumentations are disabled by default. +Only enable the instrumentations you need using the builder setter methods. + + +### HTTP Configuration + +The agent provides a configuration object for HTTP-related spans named `HttpTraceConfiguration`. +You can pass an instance of it to the `ElasticApmConfiguration` object when initializing the agent in order to customize how the HTTP spans should be handled. + +#### Filtering HTTP requests from getting traced + +By default, all of your app's HTTP requests will get traced. +You can avoid some requests from getting traced by creating your own `HttpExclusionRule`. +For example, this is an exclusion rule that prevents all requests with the host `127.0.0.1` from getting traced: + +```java +class MyHttpExclusionRule extends HttpExclusionRule { + + @Override + public boolean exclude(HttpRequest request) { + return request.url.getHost().equals("127.0.0.1"); + } +} +``` + +Then you'd need to add it to Elastic's Agent config through its `HttpTraceConfiguration`, like so: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder() + .addExclusionRule(new MyHttpExclusionRule()) + .build(); + ElasticApmConfiguration configuration = ElasticApmConfiguration.builder() + .setHttpTraceConfiguration(httpConfig) + .build(); + ElasticApmAgent.initialize(this, configuration); + } +} +``` + +#### Adding extra attributes to your HTTP requests' spans + +If the HTTP span attributes [provided by default](https://github.com/elastic/apm/tree/main/specs/agents/mobile) aren't enough, you can attach your own `HttpAttributesVisitor` to add extra params to each HTTP request being traced. +For example: + +```java +class MyHttpAttributesVisitor implements HttpAttributesVisitor { + + public void visit(AttributesBuilder attrsBuilder, HttpRequest request) { + attrsBuilder.put("my_custom_attr_key", "my_custom_attr_value"); + } +} +``` + +Then you'd need to add it to Elastic's Agent config through its `HttpTraceConfiguration`, like so: + +```java +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder() + .addHttpAttributesVisitor(new MyHttpAttributesVisitor()) + .build(); + ElasticApmConfiguration configuration = ElasticApmConfiguration.builder() + .setHttpTraceConfiguration(httpConfig) + .build(); + ElasticApmAgent.initialize(this, configuration); + } +} +``` + +### Trace spans attributes notes + +There are [common attributes](https://github.com/elastic/apm/tree/main/specs/agents/mobile) that the Elastic APM agent gathers for every Span. +However, due to the nature of Android's OS, to collect some device-related data some of the above-mentioned resources require the Host app (your app) to have specific runtime permissions granted. +If the corresponding permissions aren't granted, then the device data won't be collected, and nothing will be sent for those attributes. +This table outlines the attributes and their corresponding permissions: + +| Attribute | Used in | Requires permission | +|---|---|---| +| `net.host.connection.subtype` | All Spans | [READ_PHONE_STATE](https://developer.android.com/reference/android/Manifest.permission#READ_PHONE_STATE) | + +### Advanced configurable options + +The configurable parameters provided by the Elastic APM agent aim to help configuring common use cases in an easy way, in most of the cases it means to act as a facade between your application and the OpenTelemetry Java SDK that this agent is built on top. +If your project requires to configure more advanced aspects of the overall APM processes, you could directly apply that configuration using the [OpenTelemetry SDK](https://opentelemetry.io/docs/instrumentation/java/getting-started/), which becomes available for you to use within your project by adding the Elastic agent plugin, as explained in the agent setup guide. +Said configuration will be used by the Elastic agent for the [signals](https://opentelemetry.io/docs/concepts/signals/) it sends out of the box. + +
+ +## Dynamic configuration Dynamic + +Configuration options marked with Dynamic true can be changed at runtime when set from Kibana's [central configuration](((kibana-ref))/agent-configuration.html). + +## Option reference + +This is a list of all configuration options. + +
+ +### `recording` (0.4.0) + +A boolean specifying if the agent should be recording or not. +When recording, the agent instruments incoming HTTP requests, tracks errors and collects and sends metrics. +When not recording, the agent works as a noop, not collecting data and not communicating with the APM sever, except for polling the central configuration endpoint. +As this is a reversible switch, agent threads are not being killed when inactivated, but they will be mostly idle in this state, so the overhead should be negligible. + +You can use this setting to dynamically disable Elastic APM at runtime. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `true` | Boolean | true | \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx index ce9934d34c..4842209175 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx @@ -5,3 +5,126 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + + +
+ +Follow these steps to start reporting your Android application's performance to Elastic APM: + +1. Set up Gradle. +1. Set up your application. +1. Compile and run. +1. (Optional) Manual set up. +1. What's next?. + +
+ +## Set up Gradle + +First, add the [Elastic APM agent plugin](https://plugins.gradle.org/plugin/co.elastic.apm.android) to your application's `build.gradle` file as shown below: + +```groovy +// Android app's build.gradle file +plugins { + id "com.android.application" + id "co.elastic.apm.android" version "[latest_version]" [^1] +} +``` +[^1]: The Elastic plugin declaration must be added below the Android app plugin declaration (`com.android.application`) and below the Kotlin plugin declaration (if used). + +After adding the agent plugin, configure it. +A minimal configuration sets the Elastic APM Server endpoint as shown below: + +```groovy +// Android app's build.gradle file +plugins { + //... + id "co.elastic.apm.android" version "[latest_version]" [^1] +} + +elasticApm { + // Minimal configuration + serverUrl = "https://your.elastic.server" + + // Optional + serviceName = "your app name" [^2] + serviceVersion = "0.0.0" [^3] + apiKey = "your server api key" [^4] + secretToken = "your server auth token" [^5] +} +``` +[^1]: You can find the latest version in the [Gradle plugin portal](https://plugins.gradle.org/plugin/co.elastic.apm.android). +[^2]: Defaults to your `android.defaultConfig.applicationId` value. +[^3]: Defaults to your `android.defaultConfig.versionName` value. +[^4]: Defaults to null. +More info on API Keys [here](((ref))/security-api-create-api-key.html). +[^5]: Defaults to null. + + +When both `secretToken` and `apiKey` are provided, apiKey has priority and secretToken is ignored. + + +
+ +### For projects using minSdk version < 26 + +Due to Android's limited support for Java 8 features on devices with API level < 26, or in other words, older than Android 8.0, you must add [Java 8+ desugaring support](https://developer.android.com/studio/write/java8-support#library-desugaring) to apps with a minSdk version lower than 26. +If you don't, your app can crash when running on devices using Android OS versions older than 8.0. This is because the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java), which this SDK is built upon, uses Java 8 features. + +If your minSdk is 26 or higher, you can skip this step. + +
+ +## Set up your application + +After syncing your project with the Gradle changes above, the Elastic APM agent needs to be initialized within your [Application class](https://developer.android.com/reference/android/app/Application). +This example shows the simplest way to configure the agent: + +```java +// Your Application class + +class MyApp extends android.app.Application { + + @Override + public void onCreate() { + super.onCreate(); + ElasticApmAgent.initialize(this); [^1] + } +} +``` +[^1]: Initialize the Elastic APM agent once. + +
+ +## Compile and run + +All that's left is to compile and run your application. +That's it! + +
+ +## (Optional) Manual set up + +If you need to set up the Elastic SDK manually, without having to add the Gradle plugin as shown above, you'll need to provide the following configuration parameters at runtime: + +- Set your app name, version, and environment name, as explained here. +- Set your server connectivity parameters, as explained here. + + +Without the Gradle plugin, the Elastic SDK won't be able to provide automatic instrumentations for its Supported technologies. + + +
+ +## What's next? + +After initializing the agent (by using the gradle plugin), your application will automatically create traces for all OkHttp network requests (including those created by tools that make use of OkHttp, like Retrofit) and all [Activity](https://developer.android.com/reference/android/app/Activity) and [Fragment](https://developer.android.com/reference/androidx/fragment/app/Fragment) starting methods. + +Apart from the automatic instrumentation helped by the Gradle plugin, you'll get automatic crash reports when an unexpected error occurs in your app, regardless of whether the Gradle plugin is available or not. + +All of these events will contain a "Session ID" that links related events together—allowing you to make sense of and diagnose any issues that arise. +Head to the **APM app in ((kib))** to start exploring your data. + +If you need to customize the Elastic APM agent to your project's needs, see configuration. +If you need to create your own custom transactions, see {/* manual instrumentation */}. + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx index 380fa061bd..a2cb08b6c7 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx index 267e8757cd..f958f217f3 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx @@ -5,3 +5,5 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx index 21f86a4f8b..27316718a1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx @@ -5,3 +5,71 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] --- + + +
+ +The Elastic APM Android agent is built on top of the [OpenTelemetry Java SDK](https://opentelemetry.io) -- extending its functionality while also automatically instrumenting various APIs and frameworks. +This section lists all supported technologies. + +* Android Gradle Plugin versions +* Android runtime versions +* Languages +* UI frameworks +* Networking frameworks + +
+ +## Android Gradle Plugin versions + +| | +|---| +| Supported versions | +| >= 7.2.0 | + +
+ +## Android runtime versions + +| | +|---| +| Supported versions | +| API >= 24 | + + +If your minSdk version is lower than 26, then you must add [Java 8+ desugaring support](https://developer.android.com/studio/write/java8-support#library-desugaring) to your application. + + +
+ +## Languages + +The Java version is for the supported JDK, which is aligned with the JDK version supported by the Android Gradle plugin. +The Kotlin version refers to the Kotlin gradle plugin versions, also aligned with the versions supported by the Android Gradle plugin. + +| Language | Supported versions | +|---|---| +| Java | 11 | +| Kotlin | 1.5+ | + +
+ +## UI frameworks + +| Class | Notes | Since | +|---|---|---| +| [Activity](https://developer.android.com/reference/android/app/Activity) | Comes from the Android SDK | 0.1.0 | +| [Fragment](https://developer.android.com/reference/androidx/fragment/app/Fragment.html) | Comes from the [Android Jetpack tools](https://developer.android.com/jetpack) | 0.1.0 | + +
+ +## Networking frameworks + +Distributed tracing will only work if you are using one of the supported networking frameworks. + +For the supported HTTP libraries, the agent automatically creates spans for outgoing HTTP requests and propagates tracing headers. +The spans are named after the schema ` `, for example `GET elastic.co`. + +| Framework | Supported versions | Note | Since | +|---|---|---|---| +| OkHttp | 3.11+ | OkHttp-managed threads and Kotlin coroutine related calls are automatically traced. Calls from tools using OkHttp (such as Retrofit) are automatically traced as well. | 0.1.0 | \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx index 5e1bed5067..1860f3cec7 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx @@ -5,3 +5,33 @@ title: Android # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] --- + + +
+ +The Elastic APM Android Agent automatically measures the performance of your application and tracks errors. +It has a default configuration that suits most common use cases and built-in support for popular frameworks and technologies. +The agent is built on top of [OpenTelemetry](https://opentelemetry.io/), enabling you to add custom instrumentation with the +[OpenTelemetry Java API](https://opentelemetry.io/docs/instrumentation/java/manual/). + +
+ +## How does the Agent work? + +The Agent auto-instruments Supported technologies and records interesting events, like spans for outgoing HTTP requests and UI rendering processes. +To do this, it leverages the capability of the Android Gradle plugin API to instrument the bytecode of classes. +This means that for supported technologies, there are no code changes required. + +Spans are grouped in transactions -- by default, one for each outgoing HTTP request or UI rendering process. +It's also possible to create custom transactions with the [OpenTelemetry Java API](https://opentelemetry.io/docs/instrumentation/java/manual/), which is automatically provided to the Agent's host app. +Transactions and Spans are sent to the APM Server, where they're converted to a format suitable for Elasticsearch. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + +More detailed information on how the Agent works can be found in the {/* FAQ */}. + +
+ +## Additional components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx index 8b91188f1c..f560280592 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx @@ -5,3 +5,5 @@ title: AWS Lambda Functions # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx index 52cb544fb7..c12c6d3f92 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx @@ -5,3 +5,5 @@ title: Elastic APM agents # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx index c493472f5b..1d78b5a598 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx @@ -5,3 +5,601 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +This section describes the most commonly used parts of the API. + +The Go agent is documented using standard godoc. For complete documentation, +refer to the documentation at [pkg.go.dev/go.elastic.co/apm/v2](https://pkg.go.dev/go.elastic.co/apm/v2), +or by using the "godoc" tool. + +
+ +## Tracer API + +The initial point of contact your application will have with the Go agent +is the `apm.Tracer` type, which provides methods for reporting +transactions and errors. + +To make instrumentation simpler, the Go agent provides an initialization +function, `apm.DefaultTracer()`. This tracer is initialized the first time +`apm.DefaultTracer()` is called, and returned on subsequent calls. The tracer +returned by this function can be modified using `apm.SetDefaultTracer(tracer)`. +Calling this will close the previous default tracer, if any exists. This +tracer is configured with environment variables; see Configuration for +details. + +```go +import ( + "go.elastic.co/apm/v2" +) + +func main() { + tracer := apm.DefaultTracer() + ... +} +``` + +{/* ------------------------------------------------------------------------------------------------- */} + +
+ +## Transactions + +
+ +### `func (*Tracer) StartTransaction(name, type string) *Transaction` + +StartTransaction returns a new Transaction with the specified name and type, +and with the start time set to the current time. If you need to set the +timestamp or the parent trace context, use +Tracer.StartTransactionOptions. + +This method should be called at the beginning of a transaction such as a web +or RPC request. e.g.: + +```go +transaction := apm.DefaultTracer().StartTransaction("GET /", "request") +``` + +Transactions will be grouped by type and name in the Elastic APM app. + +After starting a transaction, you can record a result and add context to +further describe the transaction. + +```go +transaction.Result = "Success" +transaction.Context.SetLabel("region", "us-east-1") +``` + +See Context for more details on setting transaction context. + +
+ +### `func (*Tracer) StartTransactionOptions(name, type string, opts TransactionOptions) *Transaction` + +StartTransactionOptions is essentially the same as StartTransaction, but +also accepts an options struct. This struct allows you to specify the +parent trace context and/or the transaction's start time. + +```go +opts := apm.TransactionOptions{ + Start: time.Now(), + TraceContext: parentTraceContext, +} +transaction := apm.DefaultTracer().StartTransactionOptions("GET /", "request", opts) +``` + +
+ +### `func (*Transaction) End()` + +End enqueues the transaction for sending to the Elastic APM server. +The transaction must not be modified after this, but it may still +be used for starting spans. + +The transaction's duration is calculated as the amount of time +elapsed between the start of the transaction and this call. To override +this behavior, the transaction's `Duration` field may be set before +calling End. + +```go +transaction.End() +``` + +
+ +### `func (*Transaction) TraceContext() TraceContext` + +TraceContext returns the transaction's trace context. + +
+ +### `func (*Transaction) EnsureParent() SpanID` + +EnsureParent returns the transaction's parent span ID--generating and recording one if +it did not previously have one. + +EnsureParent enables correlation with spans created by the JavaScript Real User Monitoring +(RUM) agent for the initial page load. If your backend service generates the HTML page +dynamically, you can inject the trace and parent span ID into the page in order to initialize +the JavaScript RUM agent, such that the web browser's page load appears as the root of the +trace. + +```go +var initialPageTemplate = template.Must(template.New("").Parse(` + + + + + +... + +`)) + +func initialPageHandler(w http.ResponseWriter, req *http.Request) { + err := initialPageTemplate.Execute(w, apm.TransactionFromContext(req.Context())) + if err != nil { + ... + } +} +``` + +See the [JavaScript RUM agent documentation](((apm-rum-ref))/index.html) for more information. + +
+ +### `func (*Transaction) ParentID() SpanID` + +ParentID returns the ID of the transaction's parent, or a zero (invalid) SpanID if the transaction has no parent. + +
+ +### `func ContextWithTransaction(context.Context, *Transaction) context.Context` + +ContextWithTransaction adds the transaction to the context, and returns the resulting context. + +The transaction can be retrieved using apm.TransactionFromContext. +The context may also be passed into apm.StartSpan, which uses +TransactionFromContext under the covers to create a span as a child of the transaction. + +
+ +### `func TransactionFromContext(context.Context) *Transaction` + +TransactionFromContext returns a transaction previously stored in the context using +apm.ContextWithTransaction, or nil if the context +does not contain a transaction. + +
+ +### `func DetachedContext(context.Context) context.Context` + +DetachedContext returns a new context detached from the lifetime of the input, but +which still returns the same values as the input. + +DetachedContext can be used to maintain trace context required to correlate events, +but where the operation is "fire-and-forget" and should not be affected by the +deadline or cancellation of the surrounding context. + +
+ +### `func TraceFormatter(context.Context) fmt.Formatter` + +TraceFormatter returns an implementation of [fmt.Formatter](https://golang.org/pkg/fmt/#Formatter) +that can be used to format the IDs of the transaction and span stored in the provided context. + +The formatter understands the following formats: + + - %v: trace ID, transaction ID, and (if in the context of a span) span ID, space separated + - %t: trace ID only + - %x: transaction ID only + - %s: span ID only + +The "+" option can be used to format the values in "key=value" style, with the field +names `trace.id`, `transaction.id`, and `span.id`. For example, using "%+v" as the format +would yield "trace.id=... transaction.id=... span.id=...". + +For a more in-depth example, see {/* Manual log correlation (unstructured) */}. + +{/* ------------------------------------------------------------------------------------------------- */} + +
+ +## Spans + +To describe an activity within a transaction, we create spans. The Go agent +has built-in support for generating spans for some activities, such as +database queries. You can use the API to report spans specific to your +application. + +
+ +### `func (*Transaction) StartSpan(name, spanType string, parent **Span) **Span` + +StartSpan starts and returns a new Span within the transaction, with the specified name, +type, and optional parent span, and with the start time set to the current time. +If you need to set the timestamp or parent trace context, +use Transaction.StartSpanOptions. + +If the span type contains two dots, they are assumed to separate the span type, subtype, +and action; a single dot separates span type and subtype, and the action will not be set. + +If the transaction is sampled, then the span's ID will be set, and its stacktrace will +be set if the tracer is configured accordingly. If the transaction is not sampled, then +the returned span will be silently discarded when its End method is called. To avoid any unnecessary computation for these dropped spans, call the Dropped +method. + +As a convenience, it is valid to create a span on a nil Transaction; the resulting span +will be non-nil and safe for use, but will not be reported to the APM server. + +```go +span := tx.StartSpan("SELECT FROM foo", "db.mysql.query", nil) +``` + +
+ +### `func (*Transaction) StartSpanOptions(name, spanType string, opts SpanOptions) *Span` + +StartSpanOptions is essentially the same as StartSpan, but also accepts an options struct. +This struct allows you to specify the parent trace context and/or the +spans's start time. If the parent trace context is not specified in the options, then the +span will be a direct child of the transaction. Otherwise, the parent trace context should +belong to some span descended from the transaction. + +```go +opts := apm.SpanOptions{ + Start: time.Now(), + Parent: parentSpan.TraceContext(), +} +span := tx.StartSpanOptions("SELECT FROM foo", "db.mysql.query", opts) +``` + +
+ +### `func StartSpan(ctx context.Context, name, spanType string) (*Span, context.Context)` + +StartSpan starts and returns a new Span within the sampled transaction and parent span +in the context, if any. If the span isn't dropped, it will be included in the resulting +context. + +```go +span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query") +``` + +
+ +### `func (*Span) End()` + +End marks the span as complete. The Span must not be modified after this, +but may still be used as the parent of a span. + +The span's duration will be calculated as the amount of time elapsed +since the span was started until this call. To override this behaviour, +the span's Duration field may be set before calling End. + +
+ +### `func (*Span) Dropped() bool` + +Dropped indicates whether or not the span is dropped, meaning it will not be reported to +the APM server. Spans are dropped when the created with a nil, or non-sampled transaction, +or one whose max spans limit has been reached. + +
+ +### `func (*Span) TraceContext() TraceContext` + +TraceContext returns the span's trace context. + +
+ +### `func ContextWithSpan(context.Context, *Span) context.Context` + +ContextWithSpan adds the span to the context and returns the resulting context. + +The span can be retrieved using apm.SpanFromContext. +The context may also be passed into apm.StartSpan, which uses +SpanFromContext under the covers to create another span as a child of the span. + +
+ +### `func SpanFromContext(context.Context) *Span` + +SpanFromContext returns a span previously stored in the context using +apm.ContextWithSpan, or nil if the context +does not contain a span. + +
+ +### `func (*Span) ParentID() SpanID` + +ParentID returns the ID of the span's parent. + +{/* ------------------------------------------------------------------------------------------------- */} + +
+ +## Context + +When reporting transactions and errors you can provide context to describe +those events. Built-in instrumentation will typically provide some context, +e.g. the URL and remote address for an HTTP request. You can also provide +custom context and tags. + +
+ +### `func (*Context) SetLabel(key string, value interface{})` + +SetLabel labels the transaction or error with the given key and value. +If the key contains any special characters (`.`, `*`, `"`), they will be +replaced with underscores. + +If the value is numerical or boolean, then it will be sent to the server +as a JSON number or boolean; otherwise it will converted to a string, using +`fmt.Sprint` if necessary. Numerical and boolean values are supported by +the server from version 6.7 onwards. + +String values longer than 1024 characters will be truncated. Labels are +indexed in Elasticsearch as keyword fields. + + +Before using labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +
+ +### `func (*Context) SetCustom(key string, value interface{})` + +SetCustom is used to add custom, non-indexed, contextual information to +transactions or errors. If the key contains any special characters +(`.`, `*`, `"`), they will be replaced with underscores. + +Non-indexed means the data is not searchable or aggregatable in Elasticsearch, +and you cannot build dashboards on top of the data. However, non-indexed +information is useful for other reasons, like providing contextual information +to help you quickly debug performance issues or errors. + +The value can be of any type that can be encoded using `encoding/json`. + + +Before using custom context, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +
+ +### `func (*Context) SetUsername(username string)` + +SetUsername records the username of the user associated with the transaction. + +
+ +### `func (*Context) SetUserID(id string)` + +SetUserID records the ID of the user associated with the transaction. + +
+ +### `func (*Context) SetUserEmail(email string)` + +SetUserEmail records the email address of the user associated with the transaction. + +{/* ------------------------------------------------------------------------------------------------- */} + +
+ +## Errors + +Elastic APM provides two methods of capturing an error event: reporting an error log record, +and reporting an "exception" (either a panic or an error in Go parlance). + +
+ +### `func (*Tracer) NewError(error) *Error` + +NewError returns a new Error with details taken from err. + +The exception message will be set to `err.Error()`. The exception module and type will be set +to the package and type name of the cause of the error, respectively, where the cause has the +same definition as given by [github.com/pkg/errors](https://github.com/pkg/errors). + +```go +e := apm.DefaultTracer().NewError(err) +... +e.Send() +``` + +The provided error can implement any of several interfaces to provide additional information: + +```go +// Errors implementing ErrorsStacktracer will have their stacktrace +// set based on the result of the StackTrace method. +type ErrorsStacktracer interface { + StackTrace() github.com/pkg/errors.StackTrace +} + +// Errors implementing Stacktracer will have their stacktrace +// set based on the result of the StackTrace method. +type Stacktracer interface { + StackTrace() []go.elastic.co/apm/v2/stacktrace.Frame +} + +// Errors implementing Typer will have a "type" field set to the +// result of the Type method. +type Typer interface { + Type() string +} + +// Errors implementing StringCoder will have a "code" field set to the +// result of the Code method. +type StringCoder interface { + Code() string +} + +// Errors implementing NumberCoder will have a "code" field set to the +// result of the Code method. +type NumberCoder interface { + Code() float64 +} +``` + +Errors created by with NewError will have their ID field populated with a unique ID. +This can be used in your application for correlation. + +
+ +### `func (*Tracer) NewErrorLog(ErrorLogRecord) *Error` + +NewErrorLog returns a new Error for the given ErrorLogRecord: + +```go +type ErrorLogRecord struct { + // Message holds the message for the log record, + // e.g. "failed to connect to %s". + // + // If this is empty, "[EMPTY]" will be used. + Message string + + // MessageFormat holds the non-interpolated format + // of the log record, e.g. "failed to connect to %s". + // + // This is optional. + MessageFormat string + + // Level holds the severity level of the log record. + // + // This is optional. + Level string + + // LoggerName holds the name of the logger used. + // + // This is optional. + LoggerName string + + // Error is an error associated with the log record. + // + // This is optional. + Error error +} +``` + +The resulting Error's log stacktrace will not be set. Call the SetStacktrace method to set it. + +```go +e := apm.DefaultTracer().NewErrorLog(apm.ErrorLogRecord{ + Message: "Somebody set up us the bomb.", +}) +... +e.Send() +``` + +
+ +### `func (*Error) SetTransaction(*Transaction)` + +SetTransaction associates the error with the given transaction. + +
+ +### `func (*Error) SetSpan(*Span)` + +SetSpan associates the error with the given span and the span's transaction. When calling SetSpan, +it is not necessary to also call SetTransaction. + +
+ +### `func (*Error) Send()` + +Send enqueues the error for sending to the Elastic APM server. + +
+ +### `func (*Tracer) Recovered(interface{}) *Error` + +Recovered returns an Error from the recovered value, optionally associating it with a transaction. +The error is not sent; it is the caller's responsibility to set the error's context, +and then call its `Send` method. + +```go +tx := apm.DefaultTracer().StartTransaction(...) +defer tx.End() +defer func() { + if v := recover(); v != nil { + e := apm.DefaultTracer().Recovered(v) + e.SetTransaction(tx) + e.Send() + } +}() +``` + +
+ +### `func CaptureError(context.Context, error) *Error` + +CaptureError returns a new error related to the sampled transaction and span present in the context, +if any, and sets its exception details using the given error. The Error.Handled field will be set to +true, and a stacktrace set. + +If there is no transaction in the context, or it is not being sampled, CaptureError returns nil. +As a convenience, if the provided error is nil, then CaptureError will also return nil. + +```go +if err != nil { + e := apm.CaptureError(ctx, err) + e.Send() +} +``` + +
+ +### Trace Context + +Trace context contains the ID for a transaction or span, the ID of the end-to-end trace to which the +transaction or span belongs, and trace options such as flags relating to sampling. Trace context is +propagated between processes, e.g. in HTTP headers, in order to correlate events originating from +related services. + +Elastic APM's trace context is based on the [W3C Trace Context](https://w3c.github.io/trace-context/) draft. + +
+ +### Error Context + +Errors can be associated with context just like transactions. See Context for details. +In addition, errors can be associated with an active transaction or span using +SetTransaction or {/* SetSpan */}, respectively. + +```go +tx := apm.DefaultTracer().StartTransaction("GET /foo", "request") +defer tx.End() +e := apm.DefaultTracer().NewError(err) +e.SetTransaction(tx) +e.Send() +``` + +
+ +### Tracer Config + +Many configuration attributes can be be updated dynamically via `apm.Tracer` method calls. +Please refer to the documentation at [pkg.go.dev/go.elastic.co/apm/v2#Tracer](https://pkg.go.dev/go.elastic.co/apm/v2#Tracer) +for details. The configuration methods are primarily prefixed with `Set`, such as +[apm#Tracer.SetLogger](https://pkg.go.dev/go.elastic.co/apm/v2#Tracer.SetLogger). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx index dbab74bfaf..5809c3281b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx @@ -5,3 +5,701 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import ConfigurationSetupConfig from './transclusion/configuration/setup-config.mdx' */} + +
+ +Adapt the Elastic APM Go agent to your needs with one of the following methods--listed in descending order of precedence: + + 1. [APM Agent Configuration via Kibana](((apm-app-ref))/agent-configuration.html) + (supported options are marked with Dynamic ) + + 1. In code, using the Tracer Config API + 1. Environment variables + +Configuration defined via Kibana will take precedence over the same +configuration defined in code, which takes precedence over environment +variables. If configuration is defined via Kibana, and then that is +later removed, the agent will revert to configuration defined locally +via either the Tracer Config API or environment variables. + +{/* */} + +
+ +## Dynamic configuration + +Configuration options marked with the Dynamic badge can be changed at runtime +when set from a supported source. + +The Go Agent supports [Central configuration](((apm-app-ref))/agent-configuration.html), +which allows you to fine-tune certain configurations via the APM app. +This feature is enabled in the Agent by default, with `ELASTIC_APM_CENTRAL_CONFIG`. + +## Configuration formats + +Some options require a unit, either duration or size. These need to be provided +in a specific format. + +### Duration format + +The _duration_ format is used for options like timeouts. The unit is provided as +a suffix directly after the number, without any whitespace. + +**Example:** `5ms` + +**Supported units:** + +- `ms` (milliseconds) +- `s` (seconds) +- `m` (minutes) + +### Size format + +The _size_ format is used for options such as maximum buffer sizes. The unit is +provided as a suffix directly after the number, without any whitespace. + +**Example:** `10KB` + +**Supported units:** + +- B (bytes) +- KB (kilobytes) +- MB (megabytes) +- GB (gigabytes) + + +We use the power-of-two sizing convention, e.g. 1KB = 1024B. + + +
+ +## `ELASTIC_APM_SERVER_URL` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SERVER_URL` | `http://localhost:8200` | `http://localhost:8200` | + +The URL for your Elastic APM Server. The Server supports both HTTP and HTTPS. +If you use HTTPS, then you may need to configure your client machines so +that the server certificate can be verified. You can disable certificate +verification with `ELASTIC_APM_VERIFY_SERVER_CERT`. + +
+ +## `ELASTIC_APM_SERVER_TIMEOUT` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SERVER_TIMEOUT` | `30s` | `30s` | + +The timeout for requests made to your Elastic APM server. When set to zero +or a negative value, timeouts will be disabled. + +
+ +## `ELASTIC_APM_SECRET_TOKEN` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SECRET_TOKEN` | | "A random string" | + +This string is used to ensure that only your agents can send data to your APM server. +Both the agents and the APM server have to be configured with the same secret token. + + +The secret token is sent as plain-text in every request to the server, so you +should also secure your communications using HTTPS. Unless you do so, your secret token +could be observed by an attacker. + + +
+ +## `ELASTIC_APM_API_KEY` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_API_KEY` | | "A base64-encoded string" | + +This base64-encoded string is used to ensure that only your agents can send data to your APM server. +The API key must be created using the APM Server [command line tool](((apm-guide-ref))/api-key.html). + + +The API Key is sent as plain-text in every request to the server, so you should also secure +your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. + + +
+ +## `ELASTIC_APM_SERVICE_NAME` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SERVICE_NAME` | Executable name | `my-app` | + +The name of your service or application. This is used to keep all the errors and +transactions of your service together and is the primary filter in the Elastic APM +user interface. + +If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the +executable name. e.g. if your executable is called "my-app.exe", then your +service will be identified as "my-app". + + +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. +In other words: your service name must only contain characters from the ASCII +alphabet, numbers, dashes, underscores, and spaces. + + +
+ +## `ELASTIC_APM_SERVICE_VERSION` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SERVICE_VERSION` | | A string indicating the version of the deployed service | + +A version string for the currently deployed version of the service. +If you don't version your deployments, the recommended value for this field is the commit identifier +of the deployed revision, e.g. the output of `git rev-parse HEAD`. + +
+ +## `ELASTIC_APM_SERVICE_NODE_NAME` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SERVICE_NODE_NAME` | | `my-node-name` | + +Optional name used to differentiate between nodes in a service. +Must be unique, otherwise data from multiple nodes will be aggregated together. + +If you do not specify `ELASTIC_APM_SERVICE_NODE_NAME`, service nodes will be identified using the container ID if available, +otherwise the host name. + + +This feature is fully supported in the APM Server versions >= 7.5. + + +
+ +## `ELASTIC_APM_ENVIRONMENT` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_ENVIRONMENT` | | `"production"` | + +The name of the environment this service is deployed in, e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. +It's important to be consistent when naming environments across agents. +See [environment selector](((apm-app-ref))/filters.html#environment-selector) in the APM app for more information. + + +This feature is fully supported in the APM app in Kibana versions >= 7.2. +You must use the query bar to filter for a specific environment in versions prior to 7.2. + + +
+ +## `ELASTIC_APM_ACTIVE` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_ACTIVE` | true | `false` | + +Enable or disable the agent. If set to false, then the Go agent does not send +any data to the Elastic APM server, and instrumentation overhead is minimized. + +
+ +## `ELASTIC_APM_RECORDING` + +Dynamic + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_RECORDING` | true | `false` | + +Enable or disable recording of events. If set to false, then the Go agent does not +send any events to the Elastic APM server, and instrumentation overhead is +minimized, but the agent will continue to poll the server for configuration changes. + +
+ +## `ELASTIC_APM_GLOBAL_LABELS` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_GLOBAL_LABELS` | | `dept=engineering,rack=number8` | + +Labels are added to all events. The format for labels is: `key=value[,key=value[,...]]`. +Any labels set by application via the API will override global labels with the same keys. + +This option requires APM Server 7.2 or greater, and will have no effect when using older +server versions. + +
+ +## `ELASTIC_APM_TRANSACTION_IGNORE_URLS` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | | `/heartbeat*, *.jpg` | + +A list of patterns to match HTTP requests to ignore. An incoming HTTP request +whose request line matches any of the patterns will not be reported as a transaction. + +This option supports the wildcard `*`, which matches zero or more characters. +Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. +Prefixing a pattern with `(?-i)` makes the matching case sensitive. + + +This configuration was previously known as `ELASTIC_APM_IGNORE_URLS`, which has been deprecated and will be removed in a future major +version of the agent. + + +
+ +## `ELASTIC_APM_SANITIZE_FIELD_NAMES` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `password, passwd, pwd, secret, **key, **token*, **session**, **credit**, **card**, **auth**, set-cookie, **principal**` | `sekrits` | + +A list of patterns to match the names of HTTP headers, cookies, and POST form fields to redact. + +This option supports the wildcard `*`, which matches zero or more characters. +Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. +Prefixing a pattern with `(?-i)` makes the matching case sensitive. + +
+ +## `ELASTIC_APM_CAPTURE_HEADERS` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_CAPTURE_HEADERS` | `true` | + +For transactions that are HTTP requests, the Go agent can optionally capture request and response headers. + +Possible values: `true`, `false`. + +Captured headers are subject to sanitization, per `ELASTIC_APM_SANITIZE_FIELD_NAMES`. + +
+ +## `ELASTIC_APM_CAPTURE_BODY` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_CAPTURE_BODY` | `off` | + +For transactions that are HTTP requests, the Go agent can optionally capture the request body. + +Possible values: `errors`, `transactions`, `all`, `off`. + + +Request bodies often contain sensitive values like passwords, credit card numbers, and so on. +If your service handles data like this, enable this feature with care. + + +
+ +## `ELASTIC_APM_HOSTNAME` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_HOSTNAME` | `os.Hostname()` | `app-server01` | + +The host name to use when sending error and transaction data to the APM server. + +
+ +## `ELASTIC_APM_API_REQUEST_TIME` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_API_REQUEST_TIME` | `10s` | + +The amount of time to wait before ending a request to the Elastic APM server. +When you report transactions, spans and errors, the agent will initiate a +request and send them to the server when there is enough data to send; the +request will remain open until this time has been exceeded, or until the +maximum request size has been reached. + +
+ +## `ELASTIC_APM_API_REQUEST_SIZE` + +| Environment | Default | Minimum | Maximum | +|---|---|---|---| +| `ELASTIC_APM_API_REQUEST_SIZE` | `750KB` | `1KB` | `5MB` | + +The maximum size of request bodies to send to the Elastic APM server. +The agent will maintain an in-memory buffer of compressed data for streaming +to the APM server. + +
+ +## `ELASTIC_APM_API_BUFFER_SIZE` + +| Environment | Default | Minimum | Maximum | +|---|---|---|---| +| `ELASTIC_APM_API_BUFFER_SIZE` | `1MB` | `10KB` | `100MB` | + +The maximum number of bytes of uncompressed, encoded events to store in memory +while the agent is busy. When the agent is able to, it will transfer buffered +data to the request buffer, and start streaming it to the server. If the buffer +fills up, new events will start replacing older ones. + +
+ +## `ELASTIC_APM_TRANSACTION_MAX_SPANS` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `500` | + +Limits the amount of spans that are recorded per transaction. + +This is helpful in cases where a transaction creates a large number +of spans (e.g. thousands of SQL queries). Setting an upper limit will +prevent overloading the agent and the APM server with too much work +for such edge cases. + +
+ +## `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` | `1ms` | + +Sets the minimum duration for an exit span to be reported. Spans shorter or +equal to this threshold will be dropped by the agent and reported as statistics +in the span's transaction, as long as the transaction didn't end before the span +was reported. + +When span compression is enabled (`ELASTIC_APM_SPAN_COMPRESSION_ENABLED`), the sum +of the compressed span composite is considered. + +The minimum duration allowed for this setting is 1 microsecond (`us`). + +
+ +## `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `5ms` | + +The APM agent will collect a stack trace for every recorded span whose duration +exceeds this configured value. While this is very helpful to find the exact +place in your code that causes the span, collecting this stack trace does have +some processing and storage overhead. + + +This configuration has been deprecated and will be removed in a future major version of the agent. + + +
+ +## `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `5ms` | + +The APM agent will collect a stack trace for every recorded span whose duration +exceeds this configured value. While this is very helpful to find the exact +place in your code that causes the span, collecting this stack trace does have +some processing and storage overhead. + + +This configuration was previously known as `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION`, which has been deprecated and will be removed in a future major +version of the agent. + + +
+ +## `ELASTIC_APM_STACK_TRACE_LIMIT` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `50` | + +Limits the number of frames captured for each stack trace. + +Setting the limit to 0 will disable stack trace collection, while any positive +integer value will be used as the maximum number of frames to collect. Setting +a negative value, such as -1, means that all frames will be collected. + +
+ +## `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `1.0` | + +By default, the agent will sample every transaction (e.g. request to your service). +To reduce overhead and storage requirements, set the sample rate to a value +between `0.0` and `1.0`. We still record overall time and the result for unsampled +transactions, but no context information, tags, or spans. + +
+ +## `ELASTIC_APM_METRICS_INTERVAL` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_METRICS_INTERVAL` | 30s | + +The interval at which APM agent gathers and reports metrics. Set to `0s` to disable. + +
+ +## `ELASTIC_APM_DISABLE_METRICS` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_DISABLE_METRICS` | | `system.*, **cpu**` | + +Disables the collection of certain metrics. If the name of a metric matches any of +the wildcard expressions, it will not be collected. + +This option supports the wildcard `*`, which matches zero or more characters. +Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. +Prefixing a pattern with `(?-i)` makes the matching case sensitive. + +
+ +## `ELASTIC_APM_BREAKDOWN_METRICS` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_BREAKDOWN_METRICS` | `true` | + +Capture breakdown metrics. Set to `false` to disable. + +
+ +## `ELASTIC_APM_SERVER_CERT` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SERVER_CERT` | | + +If you have configured your APM Server with a self signed TLS certificate, or you +want to pin the server certificate, specify the path to the PEM-encoded +certificate via the `ELASTIC_APM_SERVER_CERT` configuration. + +
+ +## `ELASTIC_APM_SERVER_CA_CERT_FILE` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SERVER_CA_CERT_FILE` | | + +The path to a PEM-encoded TLS Certificate Authority certificate that will be +used for verifying the server's TLS certificate chain. + +
+ +## `ELASTIC_APM_VERIFY_SERVER_CERT` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `true` | + +By default, the agent verifies the server's certificate if you use an +HTTPS connection to the APM server. Verification can be disabled by +changing this setting to `false`. This setting is ignored when +`ELASTIC_APM_SERVER_CERT` is set. + +
+ +## `ELASTIC_APM_LOG_FILE` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_LOG_FILE` | | + +`ELASTIC_APM_LOG_FILE` specifies the output file for the agent's default, internal +logger. The file will be created, or truncated if it exists, when the process starts. +By default, logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable +it. This environment variable will be ignored if a logger is configured programatically. + +There are two special file names that the agent recognizes: `stdout` and `stderr`. +These will configure the logger to write to standard output and standard error +respectively. + +
+ +## `ELASTIC_APM_LOG_LEVEL` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_LOG_LEVEL` | `"error"` | + +`ELASTIC_APM_LOG_LEVEL` specifies the log level for the agent's default, internal +logger. The only two levels used by the logger are "error" and "debug". By default, +logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable it. + +This environment variable will be ignored if a logger is configured programatically. + +
+ +### `ELASTIC_APM_CENTRAL_CONFIG` + +| Environment | Default | +|---|---| +| `ELASTIC_APM_CENTRAL_CONFIG` | `true` | + +Activate APM Agent central configuration via Kibana. By default the agent will poll the server +for agent configuration changes. This can be disabled by changing the setting to `false`. +See [APM Agent central configuration](((kibana-ref))/agent-configuration.html) for more information. + + +This feature requires APM Server v7.3 or later. + + +
+ +### `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` +| | | +|---|---| +| Environment | Default | +| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `true` | + +To enable [distributed tracing](((apm-guide-ref))/apm-distributed-tracing.html), the agent +adds trace context headers to outgoing HTTP requests made with {/* module/apmhttp */}. +These headers (`traceparent` and `tracestate`) are defined in the +[W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification. + +When this setting is `true`, the agent will also add the header `elastic-apm-traceparent` +for backwards compatibility with older versions of Elastic APM agents. + +
+ +### `ELASTIC_APM_CLOUD_PROVIDER` + +| Environment | Default | Example | +|---|---|---| +| `ELASTIC_APM_CLOUD_PROVIDER` | `"none"` | `"aws"` | + +This config value allows you to specify which cloud provider should be assumed +for metadata collection. By default, the agent will use trial and error to +automatically collect the cloud metadata. + +Valid options are `"none"`, `"auto"`, `"aws"`, `"gcp"`, and `"azure"` +If this config value is set to `"none"`, then no cloud metadata will be collected. + +
+ +## `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `true` | + +When enabled, the agent will attempt to compress _short_ exit spans that share the +same parent into a composite span. The exact duration for what is considered +_short_, depends on the compression strategy used (`same_kind` or `exact_match`). + +In order for a span to be compressible, these conditions need to be met: + +* Spans are exit spans. +* Spans are siblings (share the same parent). +* Spans have not propagated their context downstream. +* Each span duration is equal or lower to the compression strategy maximum duration. +* Spans are compressed with `same_kind` strategy when these attributes are equal: + * `span.type`. + * `span.subtype`. + * `span.context.destination.service.resource` +* Spans are compressed with `exact_match` strategy when all the previous conditions + are met and the `span.name` is equal. + +Compressing short exit spans should provide some storage savings for services that +create a lot of consecutive short exit spans to for example databases or cache +services which are generally uninteresting when viewing a trace. + + +This feature is experimental and requires APM Server v7.15 or later. + + +
+ +## `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `50ms` | + +The maximum duration to consider for compressing sibling exit spans that are an +exact match for compression. + +
+ +## `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `0ms` | + +The maximum duration to consider for compressing sibling exit spans that are of +the same kind for compression. + +
+ +## `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` + +Dynamic + +| Environment | Default | +|---|---| +| `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` | `continue` | + +This option allows some control over how the APM agent handles W3C trace-context headers on incoming requests. +By default, the traceparent and tracestate headers are used per W3C spec for distributed tracing. +However, in certain cases it can be helpful to not use the incoming traceparent header. Some example use cases: + +- An Elastic-monitored service is receiving requests with traceparent headers from unmonitored services. +- An Elastic-monitored service is publicly exposed, and does not want tracing data (trace-ids, sampling decisions) to possibly be spoofed by user requests. + +Valid options are `continue`, `restart`, and `restart_external`: + +continue + : The default behavior. An incoming `traceparent` value is used to continue the trace and determine the sampling decision. +restart + : Always ignores the `traceparent` header of incoming requests. A new trace-id will be generated and the sampling decision will be made based on `transaction_sample_rate`. A span link will be made to the incoming `traceparent`. +restart_external + : If an incoming request includes the `es` vendor flag in `tracestate`, then any `traceparent` will be considered internal and will be handled as described for **continue** above. Otherwise, any `traceparent` is considered external and will be handled as described for **restart** above. + +Starting with Elastic Observability 8.2, span links are visible in trace views. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx index a14b2a3c61..c805040f5e 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx @@ -5,3 +5,55 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import ConfigurationSetupConfig from './transclusion/configuration/setup-config.mdx' */} + +
+ +To start reporting your Go application's performance to Elastic APM, you need to do a few things: + +1. Install the Agent. +1. Instrument Go Source Code. +1. Configure the Agent. + +
+ +## Install the Agent + +Install the Elastic APM Go agent package using `go get`: + +```bash +go get -u go.elastic.co/apm/v2 +``` + +### Requirements + +You can find a list of the supported frameworks and other technologies in the +Supported Technologies section. + +
+ +## Instrument Go Source Code + +Instrumentation is the process of extending your application's code to report trace data to Elastic APM. +Go applications must be instrumented manually at the source code level. +There are two ways to instrument your applications: + +* Using {/* Built-in instrumentation modules */}. +* {/* Custom instrumentation */} +and {/* Context propagation */} with the Go Agent API. + +Where possible, use the built-in modules to report transactions served by web and RPC frameworks in your application. + +
+ +## Configure the Agent + +{/* */} + +See Configuration to learn about all available options. + +{/* The include that was here is another page */} +{/* The include that was here is another page */} +{/* The include that was here is another page */} diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx index bfa4c67962..3fcdc90a67 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx index 442454dcdd..1d70ebcc1b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx @@ -5,3 +5,5 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx index 79523bf325..d322776a7b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx @@ -5,3 +5,323 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +This page describes the technologies supported by the Elastic APM Go agent. + +If your favorite technology is not supported yet, you can vote for it by +participating in our [survey](https://docs.google.com/forms/d/e/1FAIpQLScbW7D8m-otPO7cxqeg7XstWR8vMnxG6brnXLs_TFVSTHuHvg/viewform?usp=sf_link), or joining the conversation in the [Discuss forum](https://discuss.elastic.co/c/apm). +We will use the results of the survey and Discuss topics to add support +for the most requested technologies. + +If you would like to get more involved, take a look at the {/* contributing guide */}. + +
+ +## Go + +The Elastic APM Go agent naturally requires Go. We support the last two major +Go releases as described by [Go's Release Policy](https://golang.org/doc/devel/release.html#policy): + +> Each major Go release is supported until there are two newer major releases. +> For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. + +
+ +## Web Frameworks + +We support several third-party web frameworks, as well as Go's standard `net/http` +package. Regardless of the framework, we create a transaction for each incoming +request, and name the transaction after the registered route. + +### fasthttp + +We support [valyala/fasthttp](https://github.com/valyala/fasthttp), +[v1.26.0](https://github.com/valyala/fasthttp/releases/tag/v1.26.0) and greater. + +See {/* module/apmfasthttp */} for more information +about fasthttp instrumentation. + +### httprouter + +[julienschmidt/httprouter](https://github.com/julienschmidt/httprouter) does +not use semantic versioning, but its API is relatively stable. Any recent +version should be compatible with the Elastic APM Go agent. + +See {/* module/apmhttprouter */} for more +information about httprouter instrumentation. + +### Echo + +We support the [Echo](https://echo.labstack.com/) web framework, +[v3.3.5](https://github.com/labstack/echo/releases/tag/3.3.5) and greater. + +We provide different packages for the Echo v3 and v4 versions: +`module/apmecho` for Echo v3.x, and `module/apmechov4` for Echo v4.x. + +See {/* module/apmecho */} for more information +about Echo instrumentation. + +### Gin + +We support the [Gin](https://gin-gonic.com/) web framework, +[v1.2](https://github.com/gin-gonic/gin/releases/tag/v1.2) and greater. + +See {/* module/apmgin */} for more information +about Gin instrumentation. + +### Fiber + +We support the [Fiber](https://gofiber.io/) web framework, +[v2.18.0](https://github.com/gofiber/fiber/releases/tag/v2.18.0) and greater. + +We provide package only for the Fiber v2. +See {/* module/apmfiber */} for more information +about Fiber instrumentation. + +### Beego + +We support the [Beego](https://beego.me/) web framework, +[v1.10.0](https://github.com/astaxie/beego/releases/tag/v1.10.0) and greater. + +See {/* module/apmbeego */} for more information +about Beego instrumentation. + +### gorilla/mux + +We support [gorilla/mux](http://www.gorillatoolkit.org/pkg/mux) +[v1.6.1](https://github.com/gorilla/mux/releases/tag/v1.6.1) and greater. +Older versions are not supported due to the use of gorilla.Middleware. + +See {/* module/apmgorilla */} for more information +about gorilla/mux instrumentation. + +### go-restful + +We support [go-restful](https://github.com/emicklei/go-restful), +[2.0.0](https://github.com/emicklei/go-restful/releases/tag/2.0.0) and greater. + +See {/* module/apmrestful */} for more information +about go-restful instrumentation. + +### chi + +We support [chi](https://github.com/go-chi/chi), +[v4.0.0](https://github.com/go-chi/chi/releases/tag/v4.0.0) and greater. + +See {/* module/apmchi */} for more information +about chi instrumentation. + +### negroni + +We support [negroni](https://github.com/urfave/negroni), +[v1.0.0](https://github.com/urfave/negroni/releases/tag/v1.0.0) and greater. + +See {/* module/apmnegroni */} for more information +about negroni instrumentation. + +
+ +## Databases + +### database/sql + +We support tracing requests with any `database/sql` driver, provided +the driver is registered with the Elastic APM Go agent. Spans will be +created for each statemented executed. + +When using one of the following drivers, the Elastic APM Go agent will +be able to parse the datasource name, and provide more context in the +spans it emits: + +- [lib/pq](https://github.com/lib/pq) (PostgreSQL) +- [jackc/pgx](https://github.com/jackc/pgx) (PostgreSQL) +- [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) +- [mattn/go-sqlite3](https://github.com/go-sqlite3) + +See {/* module/apmsql */} for more information +about database/sql instrumentation. + +### GORM + +We support the [GORM](http://gorm.io/) object-relational mapping library, +[v1.9](https://github.com/jinzhu/gorm/releases/tag/v1.9) and greater. +Spans will be created for each create, query, update, and delete +operation. + +As with `database/sql` support we provide additional support for the +postgres, mysql, and sqlite dialects. + +We provide different packages for the Gorm v1 and v2 versions: +`module/apmgorm` for Gorm v1.x, and `module/apmgormv2` for Gorm v2.x. + +See {/* module/apmgorm or module/apmgormv2 */} for more information +about GORM instrumentation. + +### go-pg/pg + +We support the [go-pg/pg](https://github.com/go-pg/pg) PostgreSQL ORM, +[v8.0.4](https://github.com/go-pg/pg/releases/tag/v8.0.4). Spans will +be created for each database operation. + +See {/* module/apmgopg */} for more information +about go-pg instrumentation. + +### Cassandra (gocql) + +[GoCQL](https://gocql.github.io/) does not have a stable API, so we will +provide support for the most recent API, and older versions of the API +on a best-effort basis. Spans will be created for each query. When the +batch API is used, a span will be created for the batch, and a sub-span +is created for each query in the batch. + +See {/* module/apmgocql */} for more information +about GoCQL instrumentation. + +### Redis (gomodule/redigo) + +We support [Redigo](https://github.com/gomodule/redigo), +[v2.0.0](https://github.com/gomodule/redigo/tree/v2.0.0) and greater. +We provide helper functions for reporting Redis commands as spans. + +See {/* module/apmredigo */} for more information +about Redigo instrumentation. + +### Redis (go-redis/redis) + +We support [go-redis](https://github.com/go-redis/redis), +[v6.15.3](https://github.com/go-redis/redis/tree/v6.15.3). +We provide helper functions for reporting Redis commands as spans. + +See {/* module/apmgoredis */} for more information +about go-redis instrumentation. + +### Elasticsearch + +We provide instrumentation for Elasticsearch clients. This is usable with +the [go-elasticsearch](https://github.com/elastic/go-elasticsearch) and +[olivere/elastic](https://github.com/olivere/elastic) clients, and should +also be usable with any other clients that provide a means of configuring +the underlying `net/http.RoundTripper`. + +See {/* module/apmelasticsearch */} for more +information about Elasticsearch client instrumentation. + +### MongoDB + +We provide instrumentation for the official +[MongoDB Go Driver](https://github.com/mongodb/mongo-go-driver), +[v1.0.0](https://github.com/mongodb/mongo-go-driver/releases/tag/v1.0.0) and +greater. Spans will be created for each MongoDB command executed within a +context containing a transaction. + +See {/* module/apmmongo */} for more information about +the MongoDB Go Driver instrumentation. + +### DynamoDB + +We provide instrumentation for AWS DynamoDB. This is usable with +[AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See {/* module/apmawssdkgo */} for more information +about AWS SDK Go instrumentation. + +
+ +## RPC Frameworks + +### gRPC + +We support [gRPC](https://grpc.io/) +[v1.3.0](https://github.com/grpc/grpc-go/releases/tag/v1.3.0) and greater. +We provide unary and stream interceptors for both the client and server. +The server interceptor will create a transaction for each incoming request, +and the client interceptor will create a span for each outgoing request. + +See {/* module/apmgrpc */} for more information +about gRPC instrumentation. + +
+ +## Service Frameworks + +### Go kit + +We support tracing [Go kit](https://gokit.io/) clients and servers when +using the gRPC or HTTP transport, by way of {/* module/apmgrpc */} +and {/* module/apmhttp */} respectively. + +Code examples are available at https://pkg.go.dev/go.elastic.co/apm/module/apmgokit/v2 +for getting started. + +
+ +## Logging frameworks + +### Logrus + +We support log correlation and exception tracking with +[Logrus](https://github.com/sirupsen/logrus/), +[v1.1.0](https://github.com/sirupsen/logrus/releases/tag/v1.1.0) and greater. + +See {/* module/apmlogrus */} for more information +about Logrus integration. + +### Zap + +We support log correlation and exception tracking with +[Zap](https://github.com/uber-go/zap/), +[v1.0.0](https://github.com/uber-go/zap/releases/tag/v1.0.0) and greater. + +See {/* module/apmzap */} for more information +about Zap integration. + +### Zerolog + +We support log correlation and exception tracking with +[Zerolog](https://github.com/rs/zerolog/), +[v1.12.0](https://github.com/rs/zerolog/releases/tag/v1.12.0) and greater. + +See {/* module/apmzerolog */} for more information +about Zerolog integration. + +
+ +## Object Storage + +### Amazon S3 +We provide instrumentation for AWS S3. This is usable with +[AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See {/* module/apmawssdkgo */} for more information +about AWS SDK Go instrumentation. + +### Azure Storage +We provide instrumentation for Azure Storage. This is usable with: + +- github.com/Azure/azure-storage-blob-go/azblob[Azure Blob Storage] +- github.com/Azure/azure-storage-queue-go/azqueue[Azure Queue Storage] +- github.com/Azure/azure-storage-file-go/azfile[Azure File Storage] + +See {/* module/apmazure */} for more information +about Azure SDK Go instrumentation. + +
+ +## Messaging Systems + +### Amazon SQS +We provide instrumentation for AWS SQS. This is usable with +[AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See {/* module/apmawssdkgo */} for more information +about AWS SDK Go instrumentation. + +### Amazon SNS +We provide instrumentation for AWS SNS. This is usable with +[AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See {/* module/apmawssdkgo */} for more information +about AWS SDK Go instrumentation. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx index f32045236e..d2d8296c31 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx @@ -5,3 +5,47 @@ title: Go # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM Go Agent enables you to trace the execution of operations in your [Go](https://golang.org/) +applications, sending performance metrics and errors to the Elastic APM server. +It has built-in support for popular frameworks and toolkits, +like [Gorilla](http://www.gorillatoolkit.org/) and [Gin](https://gin-gonic.com/), +as well as support for instrumenting Go's built-in [net/http](https://golang.org/pkg/net/http/), +[database/sql](https://golang.org/pkg/database/sql/) drivers. +The Agent also offers an API Documentation for custom instrumentation. + +
+ +## How does the Agent work? + +The Agent includes instrumentation modules for Supported Technologies, +each providing middleware or wrappers for recording interesting events, such as incoming HTTP requests, outgoing HTTP requests, and database queries. + +To collect data about incoming HTTP requests, install router middleware for one of the supported Web Frameworks. +Incoming requests will be recorded as transactions, along with any related panics or errors. + +To collect data for outgoing HTTP requests, instrument an `http.Client` or `http.Transport` using {/* module/apmhttp */}. +To collect data about database queries, use {/* module/apmsql */}, +which provides instrumentation for well known database drivers. + +In order to connect transactions with related spans and errors, and propagate traces between services (distributed tracing), +the agent relies on Go's built-in [context](https://golang.org/pkg/context/) package: +transactions and spans are stored in context objects. +For example, for incoming HTTP requests, in-flight trace data will be recorded in the `context` object accessible through +[net/http.Context](https://golang.org/pkg/net/http/#Request.Context). +Read more about this in {/* Context propagation */}. + +In addition to capturing events like those mentioned above, +the agent also collects system and application metrics at regular intervals. +This collection happens in a background goroutine that is automatically started when the agent is initialized. + +
+ +## Additional Components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx index ea9e00232d..41171dffdc 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx @@ -5,3 +5,5 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx index c335a2f15f..c5f1e60471 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx @@ -5,3 +5,69 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +Configure the agent with `AgentConfigBuilder` passing the `AgentConfiguration` to the `start` function. + +{/* some config example that preferably is correct unlike mine */} + +```swift +let config = AgentConfigBuilder() + .withServerUrl(URL(string: "http://localhost:8200")) + .withSecretToken("") + .build() + +Agent.start(with:config) +``` + +The `AgentConfigBuilder` can be configured with the following functions + +
+ +## Configuration options + +
+ +### `withServerUrl` + +* **Type:** URL +* **Default:** `http://127.0.0.1:8200` + +
+ +### `withSecretToken` +* **Type:** String +* **Default:** nil +* **Env:** `OTEL_EXPORTER_OTLP_HEADERS` + +Sets the secret token for connecting to an authenticated APM Server. If using the env-var, the whole header map must be defined per [OpenTelemetry Protocol Exporter Config](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md) (e.g.: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=bearer "`) + +This setting is mutually exclusive with `withApiKey` + +
+ +### `withApiKey` +* **Type:** String +* **Default:** nil +* **Env:** `OTEL_EXPORTER_OTLP_HEADERS` + +Sets the API Token for connecting to an authenticated APM Server. If using the env-var, the whole header map must be defined per [OpenTelemetry Protocol Exporter Config](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md) (e.g.: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey "`) + +This setting is mutually exclusive with `withSecretToken` + +
+ +#### `disableAgent() -> Self` +Disables the Elastic agent. This is useful for disabling the agent during development without having to remove the Elastic agent completely. A log will report `"Elastic APM Agent has been disabled."` + +
+ +# Resource Attribute Injection +In v0.5.0, the agent provides a means to set [resource attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable) using the `OTEL_RESOURCE_ATTRIBUTES` env-var. This env-var also works through the application plist. Any resource attribute can be overridden using this method, so care should be taken, as some attributes are critical to the functioning of the kibana UI. + +
+ +## `deployment.environment` +Deployment environment is set to `default`. This can be overridden using the `OTEL_RESOURCE_ATTRIBUTES` set in your deployment's plist. Use the field key as `OTEL_RESOURCE_ATTRIBUTES` and the value as `deployment.environment=staging` \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx index 8042237379..2f000e46cc 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx @@ -5,3 +5,265 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +export let source_highlighter = "coderay" + +
+ +## Requirements + +This project requires Swift `5.7`, and is intended for use in Swift-base mobile apps. + +Other platform requires: + +| platform | version | +|---|---| +| `iOS` | `11` | +| `macOS` | `10.13` | +| `tvOS` | `v11` | +| `watchOS` | `3` | + +
+ +## Add the Agent dependency +Add the Elastic APM iOS Agent to your Xcode project or your `Package.swift`. + +Here are instructions for adding a [package dependency](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app) to a standard Xcode poject. + +Details of adding dependencies to your Package.swift can be found on ['Add a Dependency on Another Swift Package'](https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode#3578941). +Below is a helpful code-snippet: + +`package.swift`: + +```swift +Package( + dependencies:[ + .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios.git", from: "0.6.0"), + ], + targets:[ + .target( + name: "MyApp", + dependencies: [ + .product(name: "iOSAgent", package: "apm-agent-ios") + ] + ), +]) +``` + +
+ +## Initialize the agent +Once the Agent has been added as a dependency, it must be initialized. + +If you're using `SwiftUI` to build your app add the following to your `App.swift`: + +```swift +import SwiftUI +import iOSAgent + +@main +struct MyApp: App { + init() { + var config = AgentConfigBuilder() + .withServerUrl(URL(string:"http://127.0.0.1:8200")) [^1] + .withSecretToken("") [^2] + .build() + + Agent.start(with: config) + } + var body: some Scene { + WindowGroup { + ContentView() + } + } +} +``` +[^1]: APM Server URL +[^2]: Set secret token for APM server connection + +If you're not using `SwiftUI` you can alternatively add the same thing to your AppDelegate file: + +`AppDelegate.swift` + +```swift +import UIKit +import iOSAgent +@main +class AppDelegate: UIResponder, UIApplicationDelegate { + func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { +var config = AgentConfigBuilder() + .withServerUrl(URL(string:"http://127.0.0.1:8200")) [^1] + .withSecretToken("") [^2] + + Agent.start(with: config) + return true + } +} +``` +[^1]: APM Server URL +[^2]: Set secret token for APM server connection + +
+ +## Instrumentation Configuration + +An optional parameter for configuring instrumentation is also available on `Agent.start`: + +```swift + ... + + let instrumentationConfig = InstrumentationConfigBuilder() + .withCrashReporting(true) + .build() + + Agent.start(with: config, instrumentationConfig) +``` + +
+ +### Configuration Options + +
+ +#### `withCrashReporting(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggle for crash reporting. Enabled by default. Since only one crash reporter can be set in iOS, this allows for 3rd party crash reporter preference without conflict. + +
+ +#### `withAppMetricInstrumentation(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggles AppMetric instrumentation. + +
+ +#### `withURLSessionInstrumentation(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggles network instrumentation. + +
+ +#### `withViewControllerInstrumentation(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggles view controller instrumentation. + +
+ +#### `withSystemMetrics(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggles metric generation for memory and cpu usage. + +
+ +#### `withLifecycleEvents(_ enable: Bool) -> Self` +* **Type:** Bool +* **Default:** true + +Toggles event generation for lifecycle events. + +
+ +## View instrumentation + +The agent provides SwiftUI.View and UIViewController instrumentation, where the load time of a View is measured using spans. +All Views simultaneously loaded will be grouped under the same starting span. +The spans' names will be dictated by the following rules, from least to highest precedence: + +1. ` - view appearing` +1. ` - view appearing` +1. The `name` passed to View extension method `reportName(_ name: String) -> View` + +The View's class name will be a swift name-mangled string, and is the least desirable naming method. If it's possible, set a navigation title on your views: + +`AllProductsList.swift` + +```swift +struct AllProductsList: View { + @EnvironmentObject var modelData : ModelData + + var body: some View { + VStack { + List(modelData.products, id: \.id) { product in + AdminProductRow(product: product) + + } + }.onAppear { + modelData.loadProducts() + }.navigationTitle("All Products") + } +} +``` + +You'll see "All Products - view appearing" in Kibana. + +If it isn't possible to set a navigation title, use `reportName(_ name: String) -> View` to set the name that will show in Kibana: + +`AllProductsList.swift` + +```swift +struct AllProductsList: View { + @EnvironmentObject var modelData : ModelData + + var body: some View { + VStack { + List(modelData.products, id: \.id) { product in + AdminProductRow(product: product) + + } + }.onAppear { + modelData.loadProducts() + }.reportName("All Products - view appearing") + } +} +``` + + +The entire string `All Products - view appearing` must be inserted to match the default formatting used for the other two naming options. + + +
+ +## MetricKit Instrumentation +Available for iOS 13 and greater, the agent provides instrumentation of key MetricKit data points: + +* Application Launch times +* Application responsiveness +* Application exit counts + +Technical details on the metric generated can be found in the [Mobile spec](https://github.com/elastic/apm/blob/main/specs/agents/mobile/metrics.md#application-metrics) + +
+ +### `application.launch.time` +This histogram metric provides launch duration broken down by `first draw`, `first draw (optimized)`, and `resumed`. More details about the MetricKit data point can be found in the [Apple documentation](https://developer.apple.com/documentation/metrickit/mxapplaunchmetric). + +
+ +### `application.responsiveness.hangtime` +A histogram of the different durations of time in which the app is too busy to handle user interaction responsively. +More details about the MetricKit data point can be found in the [Apple documentation](https://developer.apple.com/documentation/metrickit/mxappresponsivenessmetric). + +
+ +### `application.exits` +A count of application exits categorized by various attributes: `foreground` or `background`, and `normal` or abnormal, where abnormal exits are further subdivided. +More details can be found in the [Apple documentation](https://developer.apple.com/documentation/metrickit/mxappexitmetric). + +
+ +## Application Lifecycle Events +In v0.5.0 the application lifecycle events are automatically instrumented. +The technical details can be found in the [Mobile spec](https://github.com/elastic/apm/blob/main/specs/agents/mobile/events.md#application-lifecycle-events). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx index da41437d47..1c9d88de3b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx index 13f1364cf3..6630e619ce 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx @@ -5,3 +5,5 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx index e58511fe7a..af3f4c93fc 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx @@ -5,3 +5,12 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM iOS Agent automatically instruments various APIs, frameworks, and application servers. This section lists all supported technologies. + +| Framework | Version | +|---|---| +| OpenTelemetry-Swift | 1.4.1 | diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx index b4255419aa..fdd59ff2e9 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx @@ -5,3 +5,47 @@ title: iOS # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM iOS Agent measures the performance of your mobile applications in real-time. + +
+ +## How does the agent work? +The Elastic APM iOS Agent uses the [OpenTelemetry-Swift SDK](https://github.com/open-telemetry/opentelemetry-swift). +The agent automatically traces URLSessions and provides distributed traces annotated with device information along +with your back-end services instrumented with Open-Telemetry. + +The agent also captures any custom open-telemetry traces or measurements created using the OpenTelemetry-Swift API. + +
+ +## How to add instrumentation +This agent will configure the OpenTelementry-Swift `TracerProvider` and `MetricProvider`, and set them as the global OpenTelemetry providers. They can be accessed through the OpenTelemetry SDK as follows: + +```swift +let tracerProvider = OpenTelemetry.instance.tracerProvider +let meterProvider = OpenTelemetry.instance.meterProvider +``` + +These objects can be used to acquire new tracers and meters that will send their captured data to the Elastic APM Server. More details on how to use OpenTelemetry to instrument your app can be found in the [OpenTelemetry.io Swift manual instrumentation docs](https://opentelemetry.io/docs/instrumentation/swift/manual). + +Examples can be found in [opentelemetry-swift/examples](https://github.com/open-telemetry/opentelemetry-swift/tree/main/Examples). + +
+ +## Additional components +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [((es))](((ref))/index.html), and [((kib))](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). + +## Open Telemetry Components +The iOS Agent utilizes several OpenTelemetry-Swift libraries to provide automatic instrumentation of your applications and services. Details about these instrumentation libraries can be found in the official [opentelementry.io Swift Libraries documentation](https://opentelemetry.io/docs/instrumentation/swift/libraries/). + +For network instrumentation, the agent uses `NSURLSessionInstrumentation`. This provides network instrumentation in the form of spans and enables distributed tracing for all instrumented downstream services. + +Detailed information on the device, operating system, and application is provided by `SDKResourceExtension`. More information on which data points are captured can be found in the [opentelementry.io SDKResourceExtension documentation](https://opentelemetry.io/docs/instrumentation/swift/manual/#SDKResourceExtension). + +Elastic maps OpenTelemetry attributes to Elastic-specific fields. Details of these mappings can be found in the [Elastic Mobile Agent Spec](https://github.com/elastic/apm/tree/main/specs/agents/mobile). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx index 72e2f020f9..077ad191f4 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx @@ -5,3 +5,5 @@ title: Jaeger # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx index fbdfd12a6e..40c1fa4917 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx @@ -5,3 +5,58 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/java) + + + + +
+ +There are three different ways enhance the out-of-the-box instrumentation of the Java agent with manual instrumentation: + +1. {/* Public API */} + A simple and stable API that is most native to the agent. + Contains annotations to declaratively create spans. + +1. {/* OpenTelemetry bridge */} + A vendor neutral API. + If you plan to do a lot of manual instrumentation and want to reduce vendor lock-in this is probably what you're looking for. + +1. {/* OpenTracing bridge */} + A vendor neutral API that is discontinued in favor of OpenTelemetry. + +A further option is the {/* plugin api */} which uses the OpenTelemetry API and allows you to add in custom instrumentation without modifying the application. + +
+ +## Operation Modes + +All APIs allow for different operation modes in combination with the Elastic APM agent + +Noop + : If the agent is not installed, the APIs are in noop mode and do not actually record and report spans. + + Mix and Match + + If you want to leverage the auto instrumentation of Elastic APM, + but also want to create custom spans or use the API to add custom labels to the spans created by Elastic APM, + you can just do that. + + Manual instrumentation + + If you don't want Elastic APM to auto-instrument known frameworks, + but instead only rely on manual instrumentation, + disable the auto instrumentation setting the configuration option {/* `instrument` */} to `false`. + +{/* The include that was here is another page */} +{/* The include that was here is another page */} +{/* The include that was here is another page */} diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx index 33fec86e04..8038090532 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx @@ -5,3 +5,157 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `circuit_breaker_enabled` (1.14.0 performance) + +A boolean specifying whether the circuit breaker should be enabled or not. +When enabled, the agent periodically polls stress monitors to detect system/process/JVM stress state. +If ANY of the monitors detects a stress indication, the agent will become inactive, as if the +{/* `recording` */} configuration option has been set to `false`, thus reducing resource consumption to a minimum. +When inactive, the agent continues polling the same monitors in order to detect whether the stress state +has been relieved. If ALL monitors approve that the system/process/JVM is not under stress anymore, the +agent will resume and become fully functional. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `false` | Boolean | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.circuit_breaker_enabled` | `circuit_breaker_enabled` | `ELASTIC_APM_CIRCUIT_BREAKER_ENABLED` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitoring_interval` (performance) + +The interval at which the agent polls the stress monitors. Must be at least `1s`. + +Supports the duration suffixes `ms`, `s` and `m`. +Example: `5s`. + +| Default | Type | Dynamic | +|---|---|---| +| `5s` | TimeDuration | false | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitoring_interval` | `stress_monitoring_interval` | `ELASTIC_APM_STRESS_MONITORING_INTERVAL` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitor_gc_stress_threshold` (performance) + +The threshold used by the GC monitor to rely on for identifying heap stress. +The same threshold will be used for all heap pools, so that if ANY has a usage percentage that crosses it, +the agent will consider it as a heap stress. The GC monitor relies only on memory consumption measured +after a recent GC. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `0.95` | Double | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitor_gc_stress_threshold` | `stress_monitor_gc_stress_threshold` | `ELASTIC_APM_STRESS_MONITOR_GC_STRESS_THRESHOLD` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitor_gc_relief_threshold` (performance) + +The threshold used by the GC monitor to rely on for identifying when the heap is not under stress . +If `stress_monitor_gc_stress_threshold` has been crossed, the agent will consider it a heap-stress state. +In order to determine that the stress state is over, percentage of occupied memory in ALL heap pools should +be lower than this threshold. The GC monitor relies only on memory consumption measured after a recent GC. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `0.75` | Double | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitor_gc_relief_threshold` | `stress_monitor_gc_relief_threshold` | `ELASTIC_APM_STRESS_MONITOR_GC_RELIEF_THRESHOLD` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitor_cpu_duration_threshold` (performance) + +The minimal time required in order to determine whether the system is +either currently under stress, or that the stress detected previously has been relieved. +All measurements during this time must be consistent in comparison to the relevant threshold in +order to detect a change of stress state. Must be at least `1m`. + +Dynamic + +Supports the duration suffixes `ms`, `s` and `m`. +Example: `1m`. + +| Default | Type | Dynamic | +|---|---|---| +| `1m` | TimeDuration | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitor_cpu_duration_threshold` | `stress_monitor_cpu_duration_threshold` | `ELASTIC_APM_STRESS_MONITOR_CPU_DURATION_THRESHOLD` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitor_system_cpu_stress_threshold` (performance) + +The threshold used by the system CPU monitor to detect system CPU stress. +If the system CPU crosses this threshold for a duration of at least `stress_monitor_cpu_duration_threshold`, +the monitor considers this as a stress state. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `0.95` | Double | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitor_system_cpu_stress_threshold` | `stress_monitor_system_cpu_stress_threshold` | `ELASTIC_APM_STRESS_MONITOR_SYSTEM_CPU_STRESS_THRESHOLD` | + +{/* This file is auto generated. Please make your changes in *Configuration.java (for example CoreConfiguration.java) and execute ConfigurationExporter */} + +
+ +## `stress_monitor_system_cpu_relief_threshold` (performance) + +The threshold used by the system CPU monitor to determine that the system is +not under CPU stress. If the monitor detected a CPU stress, the measured system CPU needs to be below +this threshold for a duration of at least `stress_monitor_cpu_duration_threshold` in order for the +monitor to decide that the CPU stress has been relieved. + +Dynamic + +| Default | Type | Dynamic | +|---|---|---| +| `0.8` | Double | true | + +| Java System Properties | Property file | Environment | +|---|---|---| +| `elastic.apm.stress_monitor_system_cpu_relief_threshold` | `stress_monitor_system_cpu_relief_threshold` | `ELASTIC_APM_STRESS_MONITOR_SYSTEM_CPU_RELIEF_THRESHOLD` | + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx index 4ccbdb1356..cb21b7f7b0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx @@ -5,3 +5,117 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import AwsLambdaRuntimes from './transclusion/supported-technologies/aws-lambda-runtimes.mdx' */} +{/* import LambdaSelectorLambdaAttributesSelector from '../../lambda/transclusion/lambda-selector/lambda-attributes-selector.mdx' */} +{/* import LambdaSelectorExtensionArnReplacement from '../../lambda/transclusion/lambda-selector/extension-arn-replacement.mdx' */} +{/* import LambdaJavaArnReplacement from './transclusion/lambda/java-arn-replacement.mdx' */} +{/* import AddExtensionLayerWidget from '../../lambda/transclusion/add-extension/add-extension-layer-widget.mdx' */} +{/* import LambdaConfigureLambdaWidget from './transclusion/lambda/configure-lambda-widget.mdx' */} + +
+ +export let layer_section_type = "with-agent" + +The Java APM Agent can be used with AWS Lambda to monitor the execution of your AWS Lambda functions. + +
+ +## Quick Start + +To get started with APM for your Java AWS Lambda functions, follow the steps below. + +
+ +### Prerequisites + +1. You need an APM Server to send APM data to. Follow the [APM Quick start](((apm-guide-ref))/apm-quick-start.html) if you have not set one up yet. For the best-possible performance, we recommend setting up APM on ((ecloud)) in the same AWS region as your AWS Lambda functions. +1. Make sure you are using one of the supported AWS Lambda Java runtimes: + + {/* */} + +### Step 1: Select the AWS Region and Architecture + +{/* */} + +### Step 2: Add the APM Layers to your Lambda function + +{/* */} + +{/* */} + +Both the [((apm-lambda-ext))](((apm-lambda-ref))/aws-lambda-arch.html) and the Java APM Agent are added to your Lambda function as [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html). Therefore, you need to add the corresponding Layer ARNs (identifiers) to your Lambda function. + +{/* */} + +### Step 3: Configure APM on AWS Lambda + +The ((apm-lambda-ext)) and the APM Java agent are configured through environment variables on the AWS Lambda function. + +For the minimal configuration, you will need the _APM Server URL_ to set the destination for APM data and an [_APM Secret Token_](((apm-guide-ref))/secret-token.html). +If you prefer to use an [APM API key](((apm-guide-ref))/api-key.html) instead of the APM secret token, use the `ELASTIC_APM_API_KEY` environment variable instead of `ELASTIC_APM_SECRET_TOKEN` in the following configuration. + +For production environments, we recommend [using the AWS Secrets Manager to store your APM authentication key](((apm-lambda-ref))/aws-lambda-secrets-manager.html) instead of providing the secret value as plaintext in the environment variables. + +{/* */} +\<1> The [`ELASTIC_APM_SEND_STRATEGY`](((apm-lambda-ref))/aws-lambda-config-options.html#_elastic_apm_send_strategy) defines when APM data is sent to your Elastic APM backend. To reduce the execution time of your lambda functions, we recommend to use the `background` strategy in production environments with steady load scenarios. + +You can optionally fine-tune the Java agent or the [configuration of the ((apm-lambda-ext))](((apm-lambda-ref))/aws-lambda-config-options.html). + +That's it; After following the steps above, you're ready to go! +Your Lambda function invocations should be traced from now on. + +Read on to learn more about the features and limitations of the Java APM Agent on AWS Lambda Functions. + +
+ +## Features and Caveats + +The AWS Lambda as a runtime behaves differently from conventional runtimes. +While most APM and monitoring concepts apply to AWS Lambda, there are a few differences and limitations to be aware of. + +
+ +### Performance monitoring + +Elastic APM automatically measures the performance of your lambda function executions. +It records traces for database queries, external HTTP requests, +and other slow operations that happen during execution. + +By default, the agent will trace the usual supported technologies. +To trace other events, take a look at {/* additional method tracing options */}, however note that +due to its asynchronous nature, the {/* Sampling Profiler */} is not a valid option for AWS Lambda. + +
+ +### Error monitoring + +Whenever an `Exception` is thrown by your function handler method, the agent will send an error event to the APM Server +and the corresponding transaction will be recorded as a failed transaction. +Errors related to traced spans will be sent as well. + +
+ +### Caveats +* System and custom metrics are not collected for Lambda functions. This is both because most of those are irrelevant + and because the interval-based event sending model is not suitable for FaaS environments. + +* Cold starts can be significantly slower when the agent is installed. If this is an issue, following are ways to deal with slow code + starts: + + * If the only issue with slower cold starts is Lambda timing out, consider increasing the configured timeout. + * The higher memory limit you would allow for your Function, the smaller this effect would be. This is irrelevant for + subsequent Function invocations, it is only relevant for cold starts. + + * Much of the startup delay is related to the amount of enabled instrumentations. An enabled instrumentation will contribute to this + overhead regardless of it being applicable for your specific Lambda function. You can considerably reduce the related overhead by + specifying a limited list of enabled instrumentations through the {/* `enable_instrumentations` */} config. + An automatic way to generate such list is by invoking your Lambda with the agent's default configurations and a {/* */} of `INFO` or lower. After the first lambda invocation, the agent would log a message with the following format: `Used + instrumentation groups: [aws-lambda, executor, executor-collection, fork-join, ssl-context, urlconnection]`. + +* The {/* Sampling Profiler */} feature would not work because it relies on profiling sessions and + subsequent asynchronous processing of the collected data. + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx index 4f6d535795..fc8318f42b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx index 96dc891c2b..0534fa0977 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx @@ -5,3 +5,159 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +* Agent overhead +* Tuning the Agent Startup +* Tuning the Agent +* Circuit Breaker + +
+ +## Agent overhead + +Any APM Agent will impose overhead. +Here are a few different areas where that overhead might be seen. + +### Latency + +Great care is taken to keep code on critical paths as lightweight as possible. +For example, the actual reporting of events is done on a background thread. + +It is very important that both the average latency, and higher percentiles of latency are low. +That's because a low average latency means nothing if 1% of your requests experiences very poor performance. +The main sources of spikes in higher latencies are garbage collection pauses and contended locks. + +We take great care to minimize the memory allocations we do in the Java agent as much as possible. +For example, instead of allocating new objects, we take them from an object pool and return them to the pool when they are not used anymore. +More details on this process can be found [here](https://github.com/elastic/apm-agent-java/blob/main/apm-agent-core/README.md#lifecycle). +When it comes to reporting the recorded events, +we directly serialize them into the output stream of the request to the APM server while only relying on reusable buffers. +This way we can report events without allocating any objects. +We do all that in order to not add additional work for the GC which is already busy cleaning up the memory your application is allocating. + +The Java agent also uses specialized data structures (LMAX Disruptor and queues from JCTools) +when we transfer events across threads. +For example, from the application threads which record transactions to the background reporter thread. +This is to circumvent problems like lock contention and false sharing you would get from standard JDK data structures like `ArrayBlockingQueue`. + +In single-threaded benchmarks, +our Java agent imposes an overhead in the order of single-digit microseconds (µs) up to the 99.99th percentile. +The benchmarks were run on a Linux machine with an i7-7700 (3.60GHz) on Oracle JDK 10. +We are currently working on multi-threaded benchmarks. +When disabling header recording, the agent allocates less than one byte for recording an HTTP request and one JDBC (SQL) query, +including reporting those events in the background to the APM Server. + +### CPU + +Even though the Agent does most of its work in the background, serializing and compressing events, +along with sending them to the APM Server does actually also add a bit of CPU overhead. +If your application is not CPU bound, this shouldn’t matter much. +Your application is probably not CPU bound if you do (blocking) network I/O, +like communicating with databases or external services. + +In a scenario where APM Server can’t handle all of the events, +the Agent will drop data so as to not crash your application. + +### Memory + +Unless you have really small heaps, +you usually don't have to increase the heap size for the Java Agent. +It has a fairly small and static memory overhead for the object pools, and some small buffers in the order of a couple of megabytes. + +### Network + +The Agent requires some network bandwidth, as it needs to send recorded events to the APM server. +This is where it's important to know how many requests your application handles and how many of those you want to record and store. +This can be adjusted with the Sample rate. + +
+ +## Tuning the Agent Startup + +When the Java agent starts, it needs to initialize various components of the agent, connect +to the APM server, and instrument any already loaded classes that it has been configured to +trace. This takes some time and resources, and if done synchronously on the main thread (which is +the default when using `-javaagent`) will delay the start of the application until complete. + +We provide several options to tune the startup, targeted at three startup use cases: + +1. Immediate synchronous agent start + The application needs to have instrumentation immediately applied, regardless of startup + time cost - typically because you don't want to miss any traces/transactions right from the + beginning of the application, or some types of actions only happen at initialization and need + to be instrumented before the first instance is created (such as setting up Prepared Statements). + In this use case, use the `-javaagent` command-line flag as per {/* Manual setup with `-javaagent` flag */} + +1. Fastest start (asynchronously) + The application can accept instrumentation missing before the application starts + and also accept missing some initial traces and transactions. + In this use case you can attach to the application after startup with {/* Automatic setup with `apm-agent-attach-cli.jar` */} + or if you are using the `-javaagent` command-line flag you can start the agent asynchronously + by setting the `elastic.apm.start_async` property (since 1.29.0), eg `java -Delastic.apm.start_async ...` + (you can use `elastic.apm.delay_agent_premain_ms=0` in earlier versions) + +1. Minimized synchronous start + The application needs to have instrumentation immediately applied, but needs to minimize the + time before the application starts. This requires some tradeoff: in order to reduce the + synchronous startup time, the number of instrumentations applied needs to be minimized + through the `enable_instrumentations` option. + In this use case you should identify the smallest set of instrumentation groups you can + accept for your application monitoring, and use the `enable_instrumentations` configuration + option detailed in the configuration guide. The smallest set of instrumentations + can be found in the agent logs after normal termination of the application (since version 1.29.0). + In addition to that you can run the agent with logging level set to DEBUG, and view the statistics + produced by the agent on normal termination of the application. + +
+ +## Tuning the Agent + +The Java agent offers a variety of configuration options, +some of which can have a significant impact on performance. +To make it easy to determine which options impact performance, +we've tagged certain configuration options in the documentation with _(performance)_. + +
+ +### Sample rate + +_Sample rate_ is the percentage of requests which should be recorded and sent to the APM Server. +(For pre-8.0 servers, unsampled requests are sent without contextual information which reduces +transfer and storage sizes; from 8.0 unsampled requests are not sent at all.) +What is an ideal sample rate? Unfortunately, there's no one-size-fits-all answer to that question. +Sampling comes down to your preferences and your application. +The more you want to sample, the more network bandwidth and disk space you’ll need. + +It’s important to note that the latency of an application won’t be affected much by the agent, +even if you sample at 100%. +However, the background reporter thread has some work to do when serializing and gzipping events. + +The sample rate can be changed by altering the {/* `transaction_sample_rate` (performance) */}. + +### Stack trace collection + +If a span, e.g., a captured JDBC query, takes longer than 5ms, +we capture the stack trace so that you can easily find the code path which lead to the query. +Stack traces can be quite long, taking up bandwidth and disk space, and also requiring object allocations. +But because we are processing the stack trace asynchronously, it adds very little latency. +Upping the {/* `span_stack_trace_min_duration` (performance) */} or disabling stack trace collection altogether can gain you a bit of performance if needed. + +### Recording headers and cookies + +By default, the Java agent records all request and response headers, including cookies. +Disabling {/* `capture_headers` (performance) */} can save allocations, network bandwidth, and disk space. + +
+ +## Circuit Breaker + +When enabled, the agent periodically polls stress monitors to detect system/process/JVM stress state. +If ANY of the monitors detects a stress indication, the agent will become inactive, as if the +{/* `recording` */} configuration option has been set to `false`, thus reducing resource consumption to a minimum. +When inactive, the agent continues polling the same monitors in order to detect whether the stress state +has been relieved. If ALL monitors approve that the system/process/JVM is not under stress anymore, the +agent will resume and become fully functional. +For fine-grained Circuit Breaker configurations please refer to {/* Circuit-Breaker configuration options */}. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx index ec6efbe71a..50d712f633 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx @@ -5,3 +5,646 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import AwsLambdaRuntimes from './transclusion/supported-technologies/aws-lambda-runtimes.mdx' */} + +
+ +The Elastic APM Java Agent automatically instruments various APIs, +frameworks and application servers. +This section lists all supported technologies. + +* Java versions +* Web Frameworks +* Application Servers/Servlet Containers +* Data Stores +* Networking frameworks +* Asynchronous frameworks +* Messaging frameworks +* Scheduling frameworks +* Logging frameworks +* Process frameworks +* RPC frameworks +* AWS Lambda runtimes +* Java method monitoring +* Metrics +* Caveats + +If your favorite technology is not supported yet, +you can vote for it by participating in our +[survey](https://docs.google.com/forms/d/e/1FAIpQLScd0RYiwZGrEuxykYkv9z8Hl3exx_LKCtjsqEo1OWx8BkLrOQ/viewform?usp=sf_link). +We will use the results to add support for the most requested technologies. + +Other options are to add a dependency to the agent's {/* public API */} +in order to programmatically create custom transactions and spans, or to create +your own {/* plugin */} that will instrument the technology you want instrumented. + +If you want to extend the auto-instrumentation capabilities of the agent, +the [contributing guide](https://github.com/elastic/apm-agent-java/blob/main/CONTRIBUTING.md) should get you started. + + +If, for example, +the HTTP client library of your choice is not listed, +it means that there won't be spans for those outgoing HTTP requests. +If the web framework you are using is not supported, +the agent does not capture transactions. + + +
+ +## Java versions + + +As of version 1.33.0, Java 7 support is deprecated and will be removed in a future release + + +| Vendor | Supported versions | Notes | +|---|---|---| +| Oracle JDK | 7u60+*, 8u40+, 9, 10, 11, 17, 20 | `--module-path` has not been tested yet | +| OpenJDK | 7u60+*, 8u40+, 9, 10, 11, 17, 20 | `--module-path` has not been tested yet | +| IBM J9 VM | 8 service refresh 5+ (build 2.9 or 8.0.5.0) | {/* Sampling profiler */} is not supported | +| HP-UX JVM | 7.0.10+*, 8.0.02+ | | +| SAP JVM | 8.1.065+ | | + +\* Java 7 support is deprecated and will be removed in a future release + +**Early Java 8 and Java 7** + +Early Java 8 versions before update 40 are **not supported** because they have +several bugs that might result in JVM crashes when a java agent is active, +thus agent **will not start** on those versions. +Similarly, Java 7 versions before update 60 are not supported as they are buggy in regard to invokedynamic. + +Here is an example of the message displayed when this happens. +``` +Failed to start agent - JVM version not supported: 1.8.0_31 Java HotSpot(TM) 64-Bit Server VM 25.31-b07. +To override Java version verification, set the 'elastic.apm.disable_bootstrap_checks' System property, +or the `ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS` environment variable, to 'true'. +``` + +As this message states, you can disable this check if required by adding `-Delastic.apm.disable_bootstrap_checks=true` to +the JVM arguments, or setting `ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS=true` for the JVM environment variables. + +
+ +## Web Frameworks +| Framework | Supported versions | Description | Since | +|---|---|---|---| +| Servlet API | 3+ | A transaction will be created for all incoming HTTP requests to your Servlet API-based application. Starting in version 1.18.0, additional spans are created if the servlet dispatches execution to another servlet through the `forward` or `include` APIs, or to an error page. See also Application Servers/Servlet Containers | 1.0.0, 4.0+ (`jakarta.servlet`) since 1.28.0 | +| Spring Web MVC | 4.x, 5.x, 6.x | If you are using Spring MVC (for example with Spring Boot), the transactions are named based on your controllers (`ControllerClass#controllerMethod`). | 1.0.0, 6.x since 1.38.0 | +| Spring Webflux | 5.2.3+ | Creates transactions for incoming HTTP requests, supports annotated and functional endpoints. | 1.24.0 (experimental), 1.34.0 (GA) | +| JavaServer Faces | 2.2.x, 2.3.x, 3.0.x | If you are using JSF, transactions are named based on the requested Facelets and spans are captured for visibility into execution and rendering | 1.0.0, `jakarta.faces` since 1.28.0 | +| Spring Boot | 1.5+, 2.x, 3.x | Supports embedded Tomcat, Jetty and Undertow | 1.0.0, 3.x since 1.38.0 | +| JAX-RS | 2.x, 3.x | The transactions are named based on your resources (`ResourceClass#resourceMethod`). Note that only the packages configured in {/* `application_packages` */} are scanned for JAX-RS resources. If you don't set this option, all classes are scanned. This comes at the cost of increased startup times, however. | +| JAX-WS | | The transactions are named based on your `@javax.jws.WebService`, `@jakarta.jws.WebService` annotated classes and `@javax.jws.WebMethod`, `@jakarta.jws.WebMethod` annotated method names (`WebServiceClass#webMethod`). Note that only the packages configured in {/* `application_packages` */} are scanned for JAX-WS resources. If you don't set this option, all classes are scanned. This comes at the cost of increased startup times, however. | +| Grails | 3+ | | 1.17.0 | +| Apache Struts | 2.x | The transactions are named based on your action (`ActionClass#actionMethod`). | 1.24.0 | +| Vert.x Web | 3.6+ | Captures incoming HTTP requests as transactions | 1.24.0 (experimental) | +| Sparkjava (not Apache Spark) | 2.x | The transactions are named based on your route (`GET /foo/:bar`). | 1.25.0 | +| com.sun.net.httpserver.HttpServer | 1.7+ | Captures incoming HTTP requests as transactions | 1.25.0 | +| Javalin | 3.13.8+ | | 1.25.0 | +| Java API for WebSocket | 1.0 | Captures methods annotated with `@OnOpen`, `@OnMessage`, `@OnError`, or `@OnClose` as transactions for classes that are annotated with `@ServerEndpoint`. | 1.29.0 | + +
+ +## Application Servers/Servlet Containers +The Elastic APM Java agent has generic support for the Servlet API 3+. +However, some servers require special handling. +The servers listed here are tested by an integration test suite to make sure Elastic APM is compatible with them. +Other Servlet 3+ compliant servers will most likely work as well. + +| Server | Supported versions | +|---|---| +| {/* Tomcat */} | 7.x, 8.5.x, 9.x, 10.x | +| {/* WildFly */} | 8+ | +| {/* JBoss EAP */} | 6.4, 7.0, 7.1, 7.2 | +| {/* Jetty */} (only the `ServletContextHandler` is supported) | 9.2, 9.3, 9.4 | +| {/* WebSphere Liberty */} | 8.5.5, 18.0.x | +| {/* Undertow Servlet */} | 1.4 | +| {/* Payara */} | 4.x, 5.x | +| {/* Oracle WebLogic */} | 12.2 | + +
+ +## Data Stores +| Database | Supported versions | Description | Since | +|---|---|---|---| +| JDBC | 4.1+ | The agent automatically creates DB spans for all your JDBC queries. This includes JDBC queries executed by O/R mappers like Hibernate. | +| Elasticsearch Java REST and API clients | 5.0.2+ | The agent automatically creates Elasticsearch spans for queries done through the official REST client. | 1.0.0, async since 1.5.0, API Client since 1.32.0 | +| Hibernate Search | 5.x (on by default), 6.x (off by default) | The agent automatically creates Hibernate Search spans for queries done through the Hibernate Search API. | +| Redis Jedis | 1.4.0-4.x | The agent creates spans for interactions with the Jedis client. | 1.10.0, 4.x since 1.31.0 | +| Redis Lettuce | 3.4+ | The agent creates spans for interactions with the Lettuce client. | 1.13.0 | +| Redis Redisson | 2.1.5+ | The agent creates spans for interactions with the Redisson client. | 1.15.0 | +| MongoDB driver | 3.x | The agent creates spans for interactions with the MongoDB driver. At the moment, only the synchronous driver (mongo-java-driver) is supported. The asynchronous and reactive drivers are currently not supported. | +| MongoDB Sync Driver | 4.x | The agent creates spans for interactions with the MongoDB 4.x sync driver. This provides support for `org.mongodb:mongodb-driver-sync` | 1.34.0 | +| Cassandra | 2.x+ | | 1.23.0 | +| AWS DynamoDB | 1.x, 2.x | The agent creates spans for interactions with the AWS DynamoDb service through the AWS Java SDK. | 1.31.0 | +| AWS S3 | 1.x, 2.x | The agent creates spans for interactions with the AWS S3 service through the AWS Java SDK. | 1.31.0 | + +
+ +## Networking frameworks +Distributed tracing will only work if you are using one of the supported networking frameworks. + +For the supported HTTP libraries, the agent automatically creates spans for outgoing HTTP requests and propagates tracing headers. +The spans are named after the schema ` `, for example `GET elastic.co`. + +| Framework | Supported versions | Note | Since | +|---|---|---|---| +| Apache HttpClient | 4.3+ | | 0.7.0 (4.3+) 1.8.0 (4.0+) | +| Apache HttpClient (Legacy) | 3.0+ | Requires setting {/* `instrument_ancient_bytecode` */} to `true` | 1.35.0 | +| Apache HttpAsyncClient | 4.0+ | | 1.6.0 | +| Spring RestTemplate | 3.1.1+ | | 0.7.0 | +| OkHttp | 2, 3, 4 (4.4+ since 1.22.0) | | 1.4.0 (synchronous calls via `Call#execute()`) 1.5.0 (async calls via `Call#enquene(Callback)`) | +| HttpUrlConnection | | | 1.4.0 | +| JAX-WS client | | JAX-WS clients created via [`javax.xml.ws.Service`](https://docs.oracle.com/javaee/7/api/javax/xml/ws/Service.html) inherently support context propagation as they are using `HttpUrlConnection` underneath. | 1.4.0 | +| AsyncHttpClient | 2.x | | 1.7.0 | +| Apache Dubbo | 2.5+, except for 2.7.0, 2.7.1, and 2.7.2 | | 1.17.0 | +| JDK 11 HttpClient | | | 1.18.0 | +| Vert.x WebClient | 3.6+ | | 1.25.0 | +| Spring Webclient | 5.2.3+ | | 1.33.0 (experimental), 1.34.0 (GA) | +| Finagle Http Client | 22+ | | 1.35.0 | +| LdapClient | | | 1.36.0 | + +
+ +## Asynchronous frameworks +When a Span is created in a different Thread than its parent, +the trace context has to be propagated onto this thread. + +This section lists all supported asynchronous frameworks. + + + + + `ExecutorService` + + + + + + + + The agent propagates the context for `ExecutorService` s. + + + + 1.4.0 + + + + + + + `ScheduledExecutorService` + + + + + + + + The agent propagates the context for `ScheduledExecutorService#schedule` (this does not include `scheduleAtFixedRate` or `scheduleWithFixedDelay`. + + + + 1.17.0 + + + + + + + `ForkJoinPool` + + + + + + + + The agent propagates the context for `ForkJoinPool` s. + + + + 1.17.0 + + + + + + + Scala Future + + + + 2.13.x + + + + The agent propagates the context when using the `scala.concurrent.Future` or `scala.concurrent.Promise`. + It will propagate the context when using chaining methods such as `map`, `flatMap`, `traverse`, ... + + + + To enable Scala Future support, you need to enable experimental plugins. + + + + + + 1.18.0 + + + + + + + Reactor + + + + 3.2.x+ + + + + The agent propagates the context for `Flux` and `Mono`. + + + + 1.24.0 (experimental), 1.34.0 (GA) + + + + + + + + +
+ +## Messaging frameworks +When using a messaging framework, sender context is propagated so that receiver events are correlated to the +same trace. + +| Framework | Supported versions | Description | Since | +|---|---|---|---| +| JMS | 1.1, 2.0 | The agent captures JMS sends and receives as spans/transactions | `javax.jms` since 1.13.0, `jakarta.jms` since 1.40.0 | +| Kafka | \<0.11.0 - without distributed tracing; 0.11.0+ - full support | The agent captures Kafka record sends and polls. Kafka streams are not traced. | 1.13.0 | +| RabbitMQ | 3.x - 5.x | The agent captures RabbitMQ Message sends, consumption and polling | 1.20.0 | +| AWS SQS | 1.x, 2.x | The agent captures SQS Message sends and polling as well as SQS message sends and consumption through JMS. | 1.34.0 | + +### Distributed Tracing + +The Java agent instrumentation for messaging system clients includes both senders and receivers. +When an instrumented client sends a message within a traced transaction, a `send` span is created. In addition, if the messaging system +supports message/record headers/annotations, the agent would add the `tracecontext` headers to enable distributed tracing. + +On the receiver side, instrumented clients will attempt to create the proper distributed trace linkage in one of several ways, depending +on how messages are received: + +* _Passive message handling:_ when the message handling logic is applied by implementing a passive message listener API (like + `javax.jms.MessageListener#onMessage` for example), creating the receiver transaction is mostly straightforward as the instrumented API + method invocation encapsulates message handling. Still, there are two use cases to consider: + + * _Single message handling:_ when the message listener API accepts a single message, the agent would create a `messaging` typed + transaction per each received message, as a child transaction of the `send` span that corresponds the received message and with the same + trace ID + + * _Batch message handling:_ when the message listener API accepts a batch of messages (like + `org.springframework.amqp.core.MessageListener.onMessageBatch` for example), the agent will create a single root transaction (i.e. + different trace ID from any of the `send` spans) by default to encapsulate the entire batch handling. The batch processing transaction + would be of `messaging` type, containing links__*__ to all `send` spans that correspond the messages in the batch. This can be changed + through the (non-documented) `message_batch_strategy` config option, which accepts either `BATCH_HANDLING` (default) or `SINGLE_HANDLING` + to enable the creation of a single child transaction per message. + +* _Active message polling:_ in some cases, message are consumed from the broker through active polling. + Whenever the polling action occurs while there is already an active span, the agent will create a `poll` span and add span links__*__ to + it for each message returned by the poll action that contains `tracecontext` headers. + Since such polling APIs don't provide any indication as to when message handling actually occurs, the agent needs to apply some + heuristics in order to trace message handling. There are two use cases to consider in this type of message receiving as well: + + * _Polling returns a single message:_ in such cases, the agent may apply assumptions with regard to the threads that execute the message + handling logic in order to determine when handling starts and ends. Based on that, it would create a transaction per consumed message. If + the consumed message contains the `tracecontext` headers, the `receive` transaction will be a child of the corresponding `send` span. + + * _Polling returns a message batch:_ typically, in such cases the agent will wrap the message collection and rely on the actual + iteration to create a transaction per message as the child of the corresponding `send` span and as part of the same trace. If iteration + occurs while there is already an active span, then the agent will add a link__*__ for each message `send` span to the active (parent) + span instead of creating transaction/span per message. + +_*_ Span links are supported by APM Server and Kibana since version 8.3 and by the Java agent since version 1.32.0 + +### RabbitMQ Specifics + +- `context.message.queue.name` field will contain queue name when using polling, exchange name otherwise. +- `context.message.destination.resource` field will contain `rabbitmq/XXX` where `XXX` is exchange name. + +Some exchange/queue names are normalized in order to keep low cardinality and user-friendlyness +- default exchange is indicated with ``. +- `null` exchange is normalized to ``, for example when polling without a message. +- generated queues whose name start with `amq.gen-` are normalized to `amq.gen-*`. + +
+ +## Scheduling frameworks +When using a scheduling framework a transaction for every execution will be created. + + + + + Scheduling Annotation + + + + + + + + The agent instruments any method defined in a package configured in {/* `application_packages` */} and annotated with one of the following: + `org.springframework.scheduling.annotation.Scheduled` + `org.springframework.scheduling.annotation.Schedules` + `javax.ejb.Schedule` + `javax.ejb.Schedules` + `jakarta.ejb.Schedule` + `jakarta.ejb.Schedules` in order to create a transaction with the type `scheduled`, representing the scheduled task execution + + + + 1.6.0, `jakarta.ejb.Schedule` since 1.28.0 + + + + + + + Quartz + + + + 1.0+ + + + + The agent instruments the `execute` method of any class implementing `org.quartz.Job`, as well as the `executeInternal` method of any class extending `org.springframework.scheduling.quartz.QuartzJobBean`, and creates a transaction with the type `scheduled`, representing the job execution + + + only classes from the quartz-jobs dependency will be instrumented automatically. For the instrumentation of other jobs the package must be added to the {/* `application_packages` */} parameter. + + + + + + + 1.8.0 - 2.0+ + + 1.26.0 - 1.0+ + + + + + + + TimerTask + + + + + + + + The agent instruments the `run` method in a package configured in {/* `application_packages` */} of any class extending `java.util.TimerTask`, and creates a transaction with the type `scheduled`, representing the job execution + + + + 1.18.0 + + + + + + +
+ +## Logging frameworks + +There are multiple log-related features in the agent and their support depend on the logging framework: + +- **{/* Correlation */}**: + The agent automatically injects `trace.id`, `transaction.id` and `error.id` into the MDC implementation (see below for framework specific MDC implementations used. MDC = Mapped Diagnostic Context, a standard way to enrich log messages with additional information). + For service correlation, the agent sets values for `service.name`, `service.version` and `service.environment`, using ECS log format is required (`ecs-logging-java` or reformatting). + +- **{/* Error capturing */}**: + Automatically captures exceptions for calls like `logger.error("message", exception)`. + +- **{/* Reformatting */}**: + When {/* `log_ecs_reformatting` */} is enabled, logs will be automatically reformatted into + ECS-compatible format. + + + + slf4j + 1.4.1+ + + Error capturing - 1.10.0 + + + log4j2 + + Correlation - 2.0+ + + Reformatting - 2.6+ + + + + [`org.apache.logging.log4j.ThreadContext`](https://logging.apache.org/log4j/2.x/manual/thread-context.html) is used for correlation. + + + + Correlation (traces) - 1.13.0 + + Correlation (service) - 1.29.0 + + Error capturing - 1.10.0 + + Reformatting - 1.22.0 + + + + log4j1 + + Correlation & error capture - 1.x + + Reformatting - 1.2.17 + + + + [`org.apache.log4j.MDC`](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html) is used for correlation. + + + + Correlation (traces) - 1.13.0 + + Correlation (service) - 1.38.0 + + Reformatting - 1.22.0 + + + + Logback + 1.1.0+ + + [`org.slf4j.MDC`](https://www.slf4j.org/api/org/slf4j/MDC.html) is used for correlation. + + + + Correlation (traces) - 1.0.0 + + Correlation (service) - 1.38.0 + + + + JBoss Logging + 3.0.0+ + http://javadox.com/org.jboss.logging/jboss-logging/3.3.0.Final/org/jboss/logging/MDC.html[`org.jboss.logging.MDC`] is used for correlation. + + Correlation (traces) - 1.23.0 (LogManager 1.30.0) + + Correlation (service) - 1.38.0 + + + + JUL - `java.util.logging` + All supported Java versions + + Correlation is only supported with ECS logging (library or reformatting) as JUL does + not provide any MDC implementation. + + + Correlation (traces) - 1.35.0 (requires ECS logging) + + Correlation (service) - 1.38.0 (requires ECS logging) + + Reformatting - 1.31.0 + + + + Tomcat JULI + 7.0.0+ + + Trace correlation is only supported with ECS logging (library or reformatting) as JUL does + not provide any MDC implementation. + + Tomcat access logs are not supported. + + + Correlation (traces) - 1.35.0 (requires ECS logging) + + Correlation (service) - 1.38.0 (requires ECS logging) + + Reformatting - 1.35.0 + + + + +
+ +## Process frameworks + +| Framework | Supported versions | Description | Since | +|---|---|---|---| +| `java.lang.Process` | | Instruments `java.lang.Process` execution. Java 9 API using `ProcessHandler` is not supported yet. | 1.13.0 | +| Apache commons-exec | 1.3 | Async process support through `org.apache.commons.exec.DefaultExecutor` and subclasses instrumentation. | 1.13.0 | + +
+ +## RPC frameworks + +| Framework | Supported versions | Description | Since | +|---|---|---|---| +| gRPC | 1.6.1+ | Client (synchronous & asynchronous) & Server instrumentation. Streaming calls are currently not instrumented. | 1.16.0 | + +
+ +## AWS Lambda runtimes + +AWS Lambda provides multiple [JVM base images](https://docs.aws.amazon.com/lambda/latest/dg/java-image.html). Only those that support the `AWS_LAMBDA_EXEC_WRAPPER` environment variables are supported out of the box. + +Running with unsupported images is still possible but requires providing agent configuration through environment variables +explicitly. + +{/* */} + +
+ +## Java method monitoring + +If you are seeing gaps in the span timeline and want to include additional methods, there are several options. See {/* How to find slow methods */} for more information. + +
+ +## Metrics + +| Framework | Description | Since | +|---|---|---| +| Built-in metrics | The agent sends various system, JVM, and application metrics. See the {/* metrics */} documentation. | 1.3.0 | +| JMX | Set the configuration option {/* `capture_jmx_metrics` */} in order to monitor any JMX metric. | 1.11.0 | +| Micrometer | Automatically detects and reports the metrics of each `MeterRegistry`. See {/* Micrometer metrics */} for more details. | 1.18.0 | + +
+ +## Caveats +* Other JVM languages, like Scala, Kotlin and Groovy have not been tested yet. + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx index fab4423202..2fcd25d488 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx @@ -5,3 +5,51 @@ title: Java # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/java) + + + + +
+ +The Elastic APM Java Agent automatically measures the performance of your application and tracks errors. +It has built-in support for popular frameworks and technologies, +as well as a simple {/* API */} which allows you to instrument any application, and +a {/* Plugin API */} that allows you to add custom instrumentation. + + +The minimum required version of the APM Server is 6.5.0 + + +
+ +## How does the Agent work? + +The Agent auto-instruments Supported technologies and records interesting events, +like spans for database queries and transactions for incoming HTTP requests. +To do this, it leverages the capability of the JVM to instrument the bytecode of classes. +This means that for the supported technologies, there are no code changes required. + +Spans are grouped in transactions -- by default, one for each incoming HTTP request. +But it's possible to create custom transactions not associated with an HTTP request. +Transactions and Spans are sent to the APM Server, where they're converted to a format suitable for Elasticsearch. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + +More detailed information on how the Agent works can be found in the {/* FAQ */}. + +
+ +## Additional components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx index d498d2e489..4dd2240d55 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx @@ -5,3 +5,900 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/dotnet) + + + + +
+ +The public API of the Elastic APM .NET agent lets you +customize and manually create spans and transactions, +as well as track errors. + +
+ +## Initialization + +The API does not require explicit Agent initialization—agent initialization is optional. The `Elastic.Apm.Agent.IsConfigured` property lets you check whether the agent is already initialized. + +
+ +### Implicit agent initialization + +If you don't explicitly initialize the agent, it will be started with a default component setup. This means the Agent will read configuration settings from environment variables. If you don't set an environment variable, the Agent will use the default value. For example, the `ServerUrl` default is `http://localhost:8200`. + +This implicit initialization of the agent happens on the first call on the `Elastic.Apm.Agent` class. + + +One exception is the `Elastic.Apm.Agent.IsConfigured` method. This method never initializes the agent, it only checks if the agent is already initialized. + + +Another example of initialization is when you enable the Agent with one of the technology-specific methods from the Set up the Agent instructions. Specifically when the `UseElasticApm` or `UseAllElasticApm` method is called in ASP.NET Core or when the IIS module is initialized in an IIS application. + +The default agent setup should cover most of the use cases and the primary way to configure the agent is through environment variables. + +
+ +### Explicit agent initialization + +If you would like to replace one of the agent components, you can do so by calling the `Elastic.Apm.Agent.Setup(AgentComponents)` method. +In the AgentComponents you can pass following optional components to the agent: + +- `IApmLogger`: A logger implementation that will be used to print log messages. Default: A console logger. +- `IPayloadSender`: A component that receives all the captured events like spans, transactions, and metrics. The default implementation serializes all events and sends them to the Elastic APM Server +- `IConfigurationReader`: A component that reads agent configuration settings. The default implementation reads configuration through environment variables. + + +In the case of ASP.NET Core, when you register the agent, the `UseElasticApm` and the `UseAllElasticApm` methods both implicitly initialize the agent by calling the `Elastic.Apm.Agent.Setup` method internally. In that setup, the `IConfigurationReader` implementation will read configuration from the ASP.NET Core configuration system in case you pass an `IConfiguration` instance to the method. The `IApmLogger` instance will also log through the configured logging provider by integrating into the ASP.NET Core logging system. + + +
+ +## Auto instrumentation in combination with the Public Agent API + +With the `Elastic.Apm.Agent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` method you can turn on auto instrumentation for supported libraries. + +In the case of ASP.NET Core, when you turn on the agent with the `UseAllElasticApm` method, the agent will do this automatically. + +With a typical console application, you need to do this manually by +calling `Elastic.Apm.Agent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` method somewhere in your application, ideally in +the startup code. + +`IDiagnosticsSubscriber` implementations are offered by the agent and they subscribe to diagnostic source events or other data sources in order to capture events automatically. + +Some examples: + +* `HttpDiagnosticsSubscriber`: captures HTTP calls through `HttpClient` and `HttpWebRequest` + + ```csharp + Agent.Subscribe(new HttpDiagnosticsSubscriber()); + ``` + +* `EfCoreDiagnosticsSubscriber`: captures database calls through Entity Framework Core +* `SqlClientDiagnosticSubscriber`: captures database calls through `SqlClient` + + + +When the agent is configured with {/* `Enabled` set to `false` */}, `Elastic.ApmAgent.Subscribe(params IDiagnosticsSubscriber[] subscribers)` will not subscribe the subscribers to +diagnostic source events. + + + +
+ +## Tracer API +The tracer gives you access to the currently active transaction and it enables you to manually start a transaction. + +You can access the API by using the static property on the Agent: `Elastic.Apm.Agent.Tracer`. + +
+ +#### `ITransaction StartTransaction(string name, string type, DistributedTracingData = null)` +Use this method to create a custom transaction. + +Note that in the case of auto-instrumentation, the agent will automatically do this for you. For example, if you have incoming HTTP calls in an ASP.NET Core application, the agent automatically starts a transaction. In these instances, this method is not needed. + +It's important to call `void End()` when the transaction has ended. +A best practice is to use the transaction in a try-catch-finally block or to use the `CaptureTransaction` method. + +Example: + +```csharp +var transaction = Elastic.Apm.Agent + .Tracer.StartTransaction("MyTransaction", ApiConstants.TypeRequest); +try +{ + //application code that is captured as a transaction +} +catch (Exception e) +{ + transaction.CaptureException(e); + throw; +} +finally +{ + transaction.End(); +} +``` + +
+ +#### `ITransaction CurrentTransaction` +Returns the currently active transaction. +See the Transaction API to customize the current transaction. + +If there is no current transaction, +this method will return `null`. + +```csharp +var transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; +``` + +
+ +#### `ISpan CurrentSpan` +Returns the currently active span. +See the Span API to customize the current span. + +If there is no current span, +this method will return `null`. + +```csharp +var span = Elastic.Apm.Agent.Tracer.CurrentSpan; +``` + +
+ +#### `CaptureTransaction` + +This is a convenient method which starts and ends a transaction and captures unhandled exceptions. +It has 3 required parameters: + +* `name`: The name of the transaction +* `type` The type of the transaction +* One of the following types which references the code that you want to capture as a transaction: + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + +And an optional parameter: + +* `distributedTracingData`: A `DistributedTracingData` instance that contains the distributed tracing information in case you want the new transaction to be a part of a trace. + +The following code is the equivalent of the previous example with the convenient API. It automatically starts and ends the transaction and reports unhandled exceptions. The `t` parameter gives you access to the `ITransaction` instance which represents the transaction that you just created. + +```csharp +Elastic.Apm.Agent.Tracer + .CaptureTransaction("TestTransaction", ApiConstants.TypeRequest, (t) => +{ + //application code that is captured as a transaction +}); +``` + +This API also supports `async` methods with the `Func` overloads. + + +The duration of the transaction will be the timespan between the first and the last line of the `async` lambda expression. + + +Example: + +```csharp +await Elastic.Apm.Agent.Tracer + .CaptureTransaction("TestTransaction", "TestType", async () => +{ + //application code that is captured as a transaction + await Task.Delay(500); //sample async code +}); +``` + + +Return value of `CaptureTransaction` method overloads that accept Task (or `Task`) is the same Task (or `Task`) instance as the one passed as the argument so if your application should continue only after the task completes you have to call `CaptureTransaction` with `await` keyword. + + +{/* ---------------------------- */} + +
+ +#### Manually propagating distributed tracing context +{/* ---------------------------- */} +Agent automatically propagates distributed tracing context for the supported technologies (see Networking client-side technologies). +If your application communicates over a protocol that is not supported by the agent +you can manually propagate distributed tracing context from the caller to the callee side using Public Agent API. + +First you serialize distributed tracing context on the caller side: + +```csharp +string outgoingDistributedTracingData = + (Agent.Tracer.CurrentSpan?.OutgoingDistributedTracingData + ?? Agent.Tracer.CurrentTransaction?.OutgoingDistributedTracingData)?.SerializeToString(); +``` +Then you transfer the resulted string to the callee side +and you continue the trace by passing deserialized distributed tracing context to any of +`ITransaction StartTransaction(string name, string type, DistributedTracingData = null)` or `CaptureTransaction` APIs - all +of these APIs have an optional `DistributedTracingData` parameter. +For example: + +```csharp +var transaction2 = Agent.Tracer.StartTransaction("Transaction2", "TestTransaction", + DistributedTracingData.TryDeserializeFromString(serializedDistributedTracingData)); +``` + + +The `OutgoingDistributedTracingData` property can be `null`. One such scenario is when the agent is disabled. + + +
+ +#### `void CaptureError(string message, string culprit, StackFrame[] frames = null, string parentId = null);` +Use this method to capture an APM error with a message and a culprit. + + +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. + + +Example: + +```csharp +Agent.Tracer.CaptureError("Something went wrong", "Database issue"); +``` + +
+ +#### `void CaptureException(Exception exception, string culprit = null, bool isHandled = false, string parentId = null);` + +Use this method to capture a .NET exception as an APM error. + + +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. + + +Example: + +```csharp +try +{ + //run my code +} +catch (Exception e) +{ + Agent.Tracer.CaptureException(e); + //handle error +} +``` + +
+ +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` + +Use this method to capture a log event as an APM error. + + +Captured errors are automatically correlated with the active transaction. If no transaction is active, the error will still appear in the APM app but will not be correlated with a transaction. + + +Example: + +```csharp +var errorLog = new ErrorLog("Error message") +{ + Level = "error", + ParamMessage = "42" +}; + +Agent.Tracer.CaptureErrorLog(errorLog); +``` + +{/* ---------------------------- */} + +
+ +## Transaction API +{/* ---------------------------- */} +A transaction describes an event captured by an Elastic APM agent monitoring a service. Transactions help combine multiple Spans into logical groups, and they are the first {/* Span */} of a service. More information on Transactions and Spans is available in the [APM data model](((apm-guide-ref))/data-model.html) documentation. + +See `ITransaction CurrentTransaction` on how to get a reference of the current transaction. + + +Calling any of the transaction's methods after `void End()` has been called is illegal. +You may only interact with a transaction when you have control over its lifecycle. + + +
+ +#### `ISpan StartSpan(string name, string type, string subType = null, string action = null)` +Start and return a new custom span as a child of the given transaction. + +It is important to call `void End()` when the span has ended or to use the `CaptureSpan` method. +A best practice is to use the span in a try-catch-finally block. + +Example: + +```csharp +ISpan span = transaction.StartSpan("Select FROM customer", + ApiConstants.TypeDb, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +try +{ + //execute db query +} +catch(Exception e) +{ + span.CaptureException(e); + throw; +} +finally +{ + span.End(); +} +``` + +
+ +#### `void SetLabel(string key, T value)` 1.7.0 + +Labels are used to add **indexed** information to transactions, spans, and errors. +Indexed means the data is searchable and aggregatable in Elasticsearch. +Multiple labels can be defined with different key-value pairs. + +* Indexed: Yes +* Elasticsearch type: [object](((ref))/object.html) +* Elasticsearch field: `labels` (previously `context.tags` in \ +Number and boolean labels were only introduced in APM Server 6.7+. +Using this API in combination with an older APM Server versions leads to validation errors. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +```csharp +transaction.SetLabel("stringSample", "bar"); +transaction.SetLabel("boolSample", true); +transaction.SetLabel("intSample", 42); +``` + +* `String key`: The tag key +* `String|Number|bool value`: The tag value + +
+ +#### `T TryGetLabel(string key, out T value)` 1.7.1 + +Returns the transaction's label in the `value` out parameter. If the `key` does not exist, this method returns false. +Labels can be added with the SetLabel method. + +```csharp +if(transaction.TryGetLabel("foo", our var myLabel)) + Console.WriteLine(myLabel); +``` + +
+ +#### `Dictionary Labels` + + +This property is obsolete and will be be removed in a future version. Use the `void SetLabel()` method instead, which allows setting labels of string, boolean and number. This property remains for now in order to not break binary compatibility, and at serialization time, the values set with `.SetLabel()` are combined with `Labels` to form the set of labels sent to APM server, with values in `Labels` taking precedence. + + +A flat mapping of user-defined labels with string values. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + + +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +```csharp +Agent.Tracer + .CaptureTransaction(TransactionName, TransactionType, + transaction => + { + transaction.Labels["foo"] = "bar"; + //application code that is captured as a transaction + }); +``` + +* `key`: The label key +* `value`: The label value + +
+ +#### `void End()` +Ends the transaction and schedules it to be reported to the APM Server. + +It is illegal to call any methods on a span instance which has already ended. +This also includes this method and `ISpan StartSpan(string name, string type, string subType = null, string action = null)`. + +Example: + +```csharp +transaction.End(); +``` + + +If you use the `CaptureTransaction` method you must not call {/* `void End()` */}. + + +
+ +#### `void CaptureException(Exception e)` +Captures an exception and reports it to the APM server. + +
+ +#### `void CaptureError(string message, string culprit, StackFrame[] frames)` +Captures a custom error and reports it to the APM server. + +This method is typically used when you want to report an error, but you don't have an `Exception` instance. + +
+ +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` +Captures a custom error and reports it to the APM server with a log attached to it. + +This method is typically used when you already log errors in your code and you want to attach this error to an APM transaction. The log will show up on the APM UI as part of the error and it will be correlated to the transaction. + +
+ +#### `CaptureSpan` + +This is a convenient method which starts and ends a span on the given transaction and captures unhandled exceptions. It has the same overloads as the `CaptureTransaction` method. + +It has 3 required parameters: + +* `name`: The name of the span +* `type` The type of the span +* One of the following types which references the code that you want to capture as a transaction: + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + +and 2 optional parameters: + +* `supType`: The subtype of the span +* `action`: The action of the span + +The following code is the equivalent of the previous example from the `ISpan StartSpan(string name, string type, string subType = null, string action = null)` section with the convenient API. It automatically starts and ends the span and reports unhandled exceptions. The `s` parameter gives you access to the `ISpan` instance which represents the span that you just created. + +```csharp +ITransaction transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; + +transaction.CaptureSpan("SampleSpan", ApiConstants.TypeDb, (s) => +{ + //execute db query +}, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +``` + +Similar to the {/* `CaptureTransaction` */} API, this method also supports `async` methods with the `Func` overloads. + + +The duration of the span will be the timespan between the first and the last line of the `async` lambda expression. + + +This example shows you how to track an `async` code block that returns a result (`Task`) as a span: + +```csharp +ITransaction transaction = Elastic.Apm.Agent.Tracer.CurrentTransaction; +var asyncResult = await transaction.CaptureSpan("Select FROM customer", ApiConstants.TypeDb, async(s) => +{ + //application code that is captured as a span + await Task.Delay(500); //sample async code + return 42; +}); +``` + + +Return value of `CaptureSpan` method overloads that accept Task (or `Task`) is the same Task (or `Task`) instance as the one passed as the argument so if your application should continue only after the task completes you have to call {/* `CaptureSpan` */} with `await` keyword. + + + +Code samples above use `Elastic.Apm.Agent.Tracer.CurrentTransaction`. In production code you should make sure the `CurrentTransaction` is not `null`. + + +
+ +#### `EnsureParentId` + +If the transaction does not have a ParentId yet, calling this method generates a new ID, sets it as the ParentId of this transaction, and returns it as a `string`. + +This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service. + +If your service generates the HTML page dynamically, initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services. + +To enable the JavaScript RUM agent in ASP.NET Core, initialize the RUM agent with the .NET agent’s current transaction: + +```JavaScript + +``` + +See the [JavaScript RUM agent documentation](((apm-rum-ref))) for more information. + +
+ +#### `Dictionary Custom` + +Custom context is used to add non-indexed, custom contextual information to transactions. +Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. +However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + +Unlike `Dictionary Labels`, the data in this property is not trimmed. + +```csharp +Agent.Tracer.CaptureTransaction(transactionName, transactionType, (transaction) => +{ + transaction.Custom["foo"] = "bar"; + transaction.End(); +}); +``` + +
+ +#### `void SetService(string serviceName, string serviceVersion)` (1.7) + +Overwrite the service name and version on a per transaction basis. This is useful when you host multiple services in a single process. + +When not set, transactions are associated with the default service. + +This method has two `string` parameters: + +* `serviceName`: The name of the service to associate with the transaction. +* `serviceVersion`: The version of the service to associate with the transaction. + +Usage: + +```csharp +var transaction = agent.Tracer.StartTransaction("Transaction1", "sample"); +transaction.SetService("MyServiceName", "1.0-beta1"); +``` + +It can also be used with the Filter API (added[1.5]): + +```csharp +Agent.AddFilter( transaction => +{ + transaction.SetService("MyServiceName", "1.0-beta1"); + return transaction; +}); +``` + +
+ +#### `Context` +You can attach additional context to manually captured transactions. + +If you use a web framework for which agent doesn't capture transactions automatically (see Web frameworks), +you can add context related to the captured transaction by setting various properties of transaction's `Context` property. +For example: + +```csharp +Agent.Tracer.CaptureTransaction("MyCustomTransaction",ApiConstants.TypeRequest, (transaction) => +{ + transaction.Context.Request = new Request(myRequestMethod, myRequestUri); + + // ... code executing the request + + transaction.Context.Response = + new Response { StatusCode = myStatusCode, Finished = wasFinished }; +}); +``` + +{/* ---------------------------- */} + +
+ +## Span API +{/* ---------------------------- */} +A span contains information about a specific code path, executed as part of a transaction. + +If for example a database query happens within a recorded transaction, +a span representing this database query may be created. +In such a case, the name of the span will contain information about the query itself, +and the type will hold information about the database type. + +
+ +#### `ISpan StartSpan(string name, string type, string subType = null, string action = null)` +Start and return a new custom span as a child of the given span. Very similar to the `ISpan StartSpan(string name, string type, string subType = null, string action = null)` method on `ITransaction`, but in this case the parent of the newly created span is a span itself. + +It is important to call `void End()` when the span has ended or to use the {/* `CaptureSpan` */} method. +A best practice is to use the span in a try-catch-finally block. + +Example: + +```csharp +ISpan childSpan = parentSpan.StartSpan("Select FROM customer", + ApiConstants.TypeDb, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +try +{ + //execute db query +} +catch(Exception e) +{ + childSpan?.CaptureException(e); + throw; +} +finally +{ + childSpan?.End(); +} +``` + +
+ +#### `void SetLabel(string key, T value)` 1.7.0 + +A flat mapping of user-defined labels with string, number or boolean values. + + +In version 6.x, labels are stored under `context.tags` in Elasticsearch. +As of version 7.x, they are stored as `labels` to comply with the [Elastic Common Schema (ECS)](https://github.com/elastic/ecs). + + + +The labels are indexed in Elasticsearch so that they are searchable and aggregatable. +By all means, +you should avoid that user specified data, +like URL parameters, +is used as a tag key as it can lead to mapping explosions. + + +```csharp +span.SetLabel("stringSample", "bar"); +span.SetLabel("boolSample", true); +span.SetLabel("intSample", 42); +``` + +* `String key`: The tag key +* `String|Number|bool value`: The tag value + +
+ +#### `T TryGetLabel(string key, out T value)` 1.7.1 + +Returns the span's label in the `value` out parameter. If the `key` does not exist, this method returns false. +Labels can be added with the SetLabel method. + +```csharp +if(span.TryGetLabel("foo", out var myLabel)) + Console.WriteLine(myLabel); +``` + +
+ +#### `Dictionary Labels` + + +This property is obsolete and will be be removed in a future version. Use the `void SetLabel()` method instead, which allows setting labels of string, boolean and number. This property remains for now in order to not break binary compatibility, and at serialization time, the values set with `.SetLabel()` are combined with `Labels` to form the set of labels sent to APM server, with values in `Labels` taking precedence. + + +Similar to `Dictionary Labels` on the {/* Transaction API */}: A flat mapping of user-defined labels with string values. + +If the key contains any special characters (`.`,`*`, `"`), they will be replaced with underscores. For example `a.b` will be stored as `a_b`. + + +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +```csharp +transaction.CaptureSpan(SpanName, SpanType, +span => + { + span.Labels["foo"] = "bar"; + //application code that is captured as a span + }); +``` + +
+ +#### `void CaptureException(Exception e)` +Captures an exception and reports it to the APM server. + +
+ +#### `void CaptureError(string message, string culprit, StackFrame[] frames)` +Captures a custom error and reports it to the APM server. + +This method is typically used when you want to report an error, but you don't have an `Exception` instance. + +
+ +#### `void CaptureErrorLog(ErrorLog errorLog, string parentId = null, Exception exception = null);` +Captures a custom error and reports it to the APM server with a log attached to it. + +This method is typically used when you already log errors in your code and you want to attach this error to an APM transaction. The log will show up on the APM UI as part of the error and it will be correlated to the transaction of the given span. + +
+ +#### `void End()` +Ends the span and schedules it to be reported to the APM Server. + +It is illegal to call any methods on a span instance which has already ended. + +
+ +#### `Context` +You can attach additional context to manually captured spans. + +If you use a database library for which agent doesn't capture spans automatically (see Data access technologies), +you can add context related to the captured database operation by setting span's `Context.Db` property. +For example: + +```csharp +Agent.Tracer.CurrentTransaction.CaptureSpan("MyDbWrite", ApiConstants.TypeDb, (span) => +{ + span.Context.Db = new Database + { Statement = myDbStatement, Type = myDbType, Instance = myDbInstance }; + + // ... code executing the database operation +}); +``` + +If you use an HTTP library for which agent doesn't capture spans automatically (see Networking client-side technologies), +you can add context related to the captured HTTP operation by setting span's `Context.Http` property. +For example: + +```csharp +Agent.Tracer.CurrentTransaction.CaptureSpan("MyHttpOperation", ApiConstants.TypeExternal, (span) => +{ + span.Context.Http = new Http + { Url = myUrl, Method = myMethod }; + + // ... code executing the HTTP operation + + span.Context.Http.StatusCode = myStatusCode; +}); +``` + +
+ +#### `CaptureSpan` + +This is a convenient method which starts and ends a child span on the given span and captures unhandled exceptions. + +Very similar to the {/* `CaptureSpan` */} method on `ITransaction`, but in this case the parent of the newly created span is a span itself. + +It has 3 required parameters: + +* `name`: The name of the span +* `type` The type of the span +* One of the following types which references the code that you want to capture as a transaction: + * `Action` + * `Action` + * `Func` + * `Func` + * `Func` + * `Func` + * `Func>` + * `Func>` + +and 2 optional parameters: + +* `supType`: The subtype of the span +* `action`: The action of the span + +The following code is the equivalent of the previous example from the `ISpan StartSpan(string name, string type, string subType = null, string action = null)` section with the convenient API. It automatically starts and ends the span and reports unhandled exceptions. The `s` parameter gives you access to the `ISpan` instance which represents the span that you just created. + +```csharp +span.CaptureSpan("SampleSpan", ApiConstants.TypeDb, (s) => +{ + //execute db query +}, ApiConstants.SubtypeMssql, ApiConstants.ActionQuery); +``` + +Similar to the {/* `CaptureTransaction` */} API, this method also supports `async` methods with the `Func` overloads. + + +The duration of the span will be the timespan between the first and the last line of the `async` lambda expression. + + +This example shows you how to track an `async` code block that returns a result (`Task`) as a span: + +```csharp +var asyncResult = await span.CaptureSpan("Select FROM customer", ApiConstants.TypeDb, async(s) => +{ + //application code that is captured as a span + await Task.Delay(500); //sample async code + return 42; +}); +``` + + +Return value of `CaptureSpan` method overloads that accept Task (or `Task`) is the same Task (or `Task`) instance as the one passed as the argument so if your application should continue only after the task completes you have to call {/* `CaptureSpan` */} with `await` keyword. + + + +Code samples above use `Elastic.Apm.Agent.Tracer.CurrentTransaction`. In production code you should make sure the `CurrentTransaction` is not `null`. + + +
+ +## Filter API (1.5) + +Use `Agent.AddFilter(filter)` to supply a filter callback. + +Each filter callback will be called just before data is sent to the APM Server. This allows you to manipulate the data being sent, like to remove sensitive information such as passwords. + +Each filter callback is called in the order they are added and will receive a payload object containing the data about to be sent to the APM Server as the only argument. + +The filter callback is synchronous and should return the manipulated payload object. If a filter callback doesn’t return any value or returns a falsy value, the remaining filter callback will not be called and the payload will not be sent to the APM Server. + +There are 3 overloads of the `Agent.AddFilter` method with the following arguments: + +- `Func`: A filter called for every transaction. +- `Func`: A filter called for every span. +- `Func`: A filter called for every error. + +Below are some usage examples of the Agent.AddFilter method. + +Drop all spans for a specific database: + +```csharp +Agent.AddFilter((ISpan span) => +{ + if (span.Context?.Db?.Instance == "VerySecretDb") + return null; + return span; +}); +``` + +Hide some data: + +```csharp +Agent.AddFilter((ITransaction transaction) => +{ + transaction.Context.Request.Url.Protocol = "[HIDDEN]"; + return transaction; +}); +``` diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx index b524193357..b79bb18123 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx @@ -5,3 +5,51 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +| Option name | Dynamic | Keywords | +|---|---|---| +| {/* `ApiKey` */} | No | Reporter | +| {/* `ApplicationNamespaces` */} | No | Stacktrace | +| {/* `CaptureBody` */} | Yes | HTTP, Performance | +| {/* `CaptureBodyContentTypes` */} | Yes | HTTP, Performance | +| {/* `CaptureHeaders` */} | Yes | HTTP, Performance | +| {/* `CentralConfig` */} | No | Core | +| {/* `CloudProvider` */} | No | Reporter | +| {/* `DisableMetrics` */} | No | Reporter | +| {/* `Enabled` */} | No | Core | +| {/* `OpentelemetryBridgeEnabled` */} | No | Core | +| {/* `Environment` */} | No | Core | +| {/* `ExcludedNamespaces` */} | No | Stacktrace | +| {/* `ExitSpanMinDuration` */} | Yes | Core, Performance | +| {/* `FlushInterval` */} | No | Reporter | +| {/* `GlobalLabels` */} | No | Core | +| {/* `IgnoreMessageQueues` */} | Yes | Messaging, Performance | +| {/* `HostName` */} | No | Core | +| {/* `LogLevel` */} | Yes | Supportability | +| {/* `MaxBatchEventCount` */} | No | Reporter | +| {/* `MaxQueueEventCount` */} | No | Reporter | +| {/* `MetricsInterval` */} | No | Reporter | +| {/* `Recording` */} | Yes | Core | +| {/* `SanitizeFieldNames` */} | Yes | Core | +| {/* `SecretToken` */} | No | Reporter | +| {/* `ServerCert` */} | No | Reporter | +| {/* `ServerUrl` */} | No | Reporter | +| {/* `ServiceName` */} | No | Core | +| {/* `ServiceNodeName` */} | No | Core | +| {/* `ServiceVersion` */} | No | Core | +| {/* `SpanCompressionEnabled` */} | Yes | Core, Performance | +| {/* `SpanCompressionExactMatchMaxDuration` */} | Yes | Core, Performance | +| {/* `SpanCompressionSameKindMaxDuration` */} | Yes | Core, Performance | +| {/* `SpanStackTraceMinDuration` */} | Yes | Stacktrace, Performance | +| {/* `StackTraceLimit` */} | Yes | Stacktrace, Performance | +| {/* `TraceContextIgnoreSampledFalse` */} | No | Core | +| {/* `TransactionIgnoreUrls` */} | Yes | HTTP, Performance | +| {/* `TransactionMaxSpans` */} | Yes | Core, Performance | +| {/* `TransactionSampleRate` */} | Yes | Core, Performance | +| {/* `TraceContinuationStrategy` */} | Yes | HTTP, Performance | +| {/* `UseElasticTraceparentHeader` */} | No | HTTP | +| {/* `UseWindowsCredentials` */} | No | Reporter | +| {/* `VerifyServerCert` */} | No | Reporter | diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx index 8438fa2c3f..6995eee6af 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx @@ -5,3 +5,93 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +export let nuget = "https://www.nuget.org/packages" + +export let dot = "." + +
+ +## Quick start + +To enable auto instrumentation for ASP.NET (Full .NET Framework), you need to install the `Elastic.Apm.AspNetFullFramework` package, add a reference +to the package in your `web.config` file, and then compile and deploy your application. + +1. Ensure you have access to the application source code and install the [`Elastic.Apm.AspNetFullFramework`]({nuget}/Elastic.Apm.AspNetFullFramework) + package. + +1. Reference the `Elastic.Apm.AspNetFullFramework` in your application's `web.config` file by adding the `ElasticApmModule` IIS module: + + ```xml + + + + + + + + + ``` + + + + There are two available configuration sources. To learn more, see {/* Configuration on ASP.NET */}. + + + + By default, the agent creates transactions for all HTTP requests, including static content: + .html pages, images, etc. + + To create transactions only for HTTP requests with dynamic content, + such as `.aspx` pages, add the `managedHandler` preCondition to your `web.config` file: + + ```xml + + + + + + + + + ``` + + + + To learn more about adding modules, see the [Microsoft docs](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/add). + + + +1. Recompile your application and deploy it. + + The `ElasticApmModule` instantiates the APM agent on the first initialization. However, there may be some scenarios where + you want to control the agent instantiation, such as configuring filters in the application start. + + To do so, the `ElasticApmModule` exposes a `CreateAgentComponents()` method that returns agent components configured to work with + ASP.NET Full Framework, which can then instantiate the agent. + + For example, you can add transaction filters to the agent in the application start: + + ```c# + public class MvcApplication : HttpApplication + { + protected void Application_Start() + { + // other application startup e.g. RouteConfig, etc. + + // set up agent with components + var agentComponents = ElasticApmModule.CreateAgentComponents(); + Agent.Setup(agentComponents); + + // add transaction filter + Agent.AddFilter((ITransaction t) => + { + t.SetLabel("foo", "bar"); + return t; + }); + } + + ``` + +Now, the `ElasticApmModule` will use the instantiated instance of the APM agent upon initialization. \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx index 010df13720..3bbb70119c 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx index 3dc3a145f0..fff061b533 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx @@ -5,3 +5,92 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/dotnet/current/performance-tuning.html) + + + + +
+ +There are many options available to tune agent performance. +Which option to adjust depends on whether you are optimizing for speed, memory usage, bandwidth or storage. + +
+ +## Sampling + +The first knob to reach for when tuning the performance of the agent is {/* `TransactionSampleRate` */}. +Adjusting the sample rate controls what percent of requests are traced. +By default, the sample rate is set at `1.0`, meaning _all_ requests are traced. + +The sample rate will impact all four performance categories, +so simply turning down the sample rate is an easy way to improve performance. + +Here's an example of setting the sample rate to 20% using {/* Configuration on ASP.NET Core */}: + +```js +{ + "ElasticApm": { + "TransactionSampleRate": 0.2 + } +} +``` + +
+ +## Stack traces + +In a complex application, +a request may produce many spans. +Capturing a stack trace for every span can result in significant memory usage. +Stack traces are also captured for every error. +There are several settings to adjust how stack traces are captured. + +
+ +### Disable capturing stack traces + +To disable capturing stack traces (for both spans and errors), +set {/* `StackTraceLimit` */} to `0`. + +
+ +### Capture stack traces only for long running spans + +In its default settings, +the APM agent collects a stack trace for every recorded span with duration longer than 5ms. +To increase the duration threshold, +set {/* `SpanStackTraceMinDuration` */}. + +
+ +### Reduce number of captured stack trace frames + +The {/* `StackTraceLimit` */} controls how many stack frames should be collected +when a capturing stack trace. + +
+ +## Disable capturing HTTP request and response headers + +Capturing HTTP request and response headers increases memory allocations, +network bandwidth and disk space used by Elasticsearch. +To disable capturing HTTP request and response headers, +set {/* `CaptureHeaders` */} to `false`. + +
+ +## Increase metrics collection interval + +The .NET agent tracks certain system and application metrics. +These metrics are regularly collected and sent to the APM Server and from there to Elasticsearch. +You can adjust the interval for metrics collection with the setting {/* `MetricsInterval` */}. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx index 27d7b502ff..a6c020c3e2 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx @@ -5,3 +5,493 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/dotnet) + + + + +
+ +If your favorite technology is not supported yet, +you can vote for it by participating in our +[survey](https://docs.google.com/forms/d/18SgsVo9asGNFMjRqwdrk3wTHNwPhtHv4jE35hZRCL6A/). +We will use the results to add support for the most requested technologies. + +Another option is to add a dependency to the agent's public API +in order to programmatically create custom transactions and spans. + +If you want to extend the auto-instrumentation capabilities of the agent, +the [contributing guide](https://github.com/elastic/apm-agent-dotnet/blob/main/CONTRIBUTING.md) should get you started. + + +If, for example, +the HTTP client library of your choice is not listed, +it means that there won't be spans for those outgoing HTTP requests. +If the web framework you are using is not supported, +the agent will not capture transactions. + + +
+ +## .NET versions + +The agent works on every .NET flavor and version that supports .NET Standard 2.0. +This means .NET Core 2.0 or newer, and .NET Framework 4.6.1 or newer. + +
+ +## Web frameworks + +Automatic instrumentation for a web framework means +a transaction is automatically created for each incoming request and it is named after the registered route. + +Automatic instrumentation is supported for the following web frameworks + +| Framework | Supported versions | Integration | +|---|---|---| +| ASP.NET Core 1.0 | 2.1+ | {/* NuGet package */} | +| ASP.NET (.NET Framework) in IIS 1.1 | 4.6.1+ (IIS 7.0 or newer) | {/* Profiler auto instrumentation */} or {/* NuGet package */} | + +
+ +## RPC Frameworks + +The agent supports gRPC on .NET Core both on the client and the server side. Every gRPC call is automatically captured by the agent. + +Streaming is not supported; for streaming use-cases, the agent does not create transactions and spans automatically. + + + + + gRPC 1.7 + + + + Grpc.Net.Client 2.23.2+ _(client side)_ + + + + {/* NuGet package */} + + + + + + + + + + + ASP.NET Core 2.1+ _(server side)_ + + + + {/* NuGet package */} + + + + + + +
+ +## Data access technologies + +Automatic instrumentation is supported for the following data access technologies + + + + + Azure CosmosDB 1.11 + + + + Microsoft.Azure.Cosmos 3.0.0+ + + Microsoft.Azure.DocumentDB.Core 2.4.1+ + + Microsoft.Azure.DocumentDB 2.4.1+ + + + + {/* NuGet package */} + + + + + + + Entity Framework Core 1.0 + + + + Microsoft.EntityFrameworkCore 2.x+ + + + + {/* NuGet package */} + + + + + + + Entity Framework 6 1.2 + + + + EntityFramework 6.2+ + + + + {/* NuGet package */} + + + + + + + Elasticsearch 1.6 + + + + Elasticsearch.Net 7.6.0+ + + NEST 7.6.0+ + + + + {/* NuGet package */} + + + + + + + MySQL 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + + MongoDB 1.9 + + + + MongoDB.Driver 2.4.4+ + + + + {/* NuGet package */} + + + + + + + Oracle 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + + PostgreSQL 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + + Redis 1.8 + + + + StackExchange.Redis 2.0.495+ + + + + {/* NuGet package */} + + + + + + + SqlClient + + + + System.Data.SqlClient 2.0.495+ 1.8 + + + + {/* NuGet package */} + + + + + + + + + + + See profiler documentation 1.12 + + + + {/* Profiler auto instrumentation */} + + + + + + + SQLite 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + +
+ +## Messaging systems + +We support automatic instrumentation for the following messaging systems + + + + + Azure Service Bus 1.10 + + + + Microsoft.Azure.ServiceBus 3.0.0+ + + Azure.Messaging.ServiceBus 7.0.0+ + + + + {/* NuGet package */} + + + + + + + Azure Queue Storage 1.10 + + + + Azure.Storage.Queues 12.6.0+ + + + + {/* NuGet package */} + + + + + + + Kafka 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + + RabbitMQ 1.12 + + + + See profiler documentation + + + + {/* Profiler auto instrumentation */} + + + + + + +
+ +## Networking client-side technologies + +Automatic instrumentation for networking client-side technology means +an HTTP span is automatically created for each outgoing HTTP request and tracing headers are propagated. + +| Framework | Supported versions | Integration | +|---|---|---| +| System.Net.Http.HttpClient 1.0 | _built-in_ | part of Elastic.Apm | +| System.Net.HttpWebRequest 1.1 | _built-in_ | part of Elastic.Apm | + +
+ +## Cloud services + +Automatic instrumentation for the following cloud services + + + + + Azure CosmosDB 1.11 + + + + Microsoft.Azure.Cosmos 3.0.0+ + + Microsoft.Azure.DocumentDB.Core 2.4.1+ + + Microsoft.Azure.DocumentDB 2.4.1+ + + + + {/* NuGet package */} + + + + + + + Azure Service Bus 1.10 + + + + Microsoft.Azure.ServiceBus 3.0.0+ + + Azure.Messaging.ServiceBus 7.0.0+ + + + + {/* NuGet package */} + + + + + + + Azure Storage 1.10 + + + + Azure.Storage.Blobs 12.8.0+ + + Azure.Storage.Queues 12.6.0+ + + Azure.Storage.Files.Shares 12.6.0+ + + + + {/* NuGet package */} + + + + + \ No newline at end of file diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx index 1386b0c6ce..c192be3131 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx @@ -5,3 +5,46 @@ title: .NET # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/dotnet) + + + + +
+ +The Elastic APM .NET Agent automatically measures the performance of your application and tracks errors. +It has built-in support for the most popular frameworks, +as well as a simple API which allows you to instrument any application. + +
+ +## How does the Agent work? + +The agent auto-instruments supported technologies and records interesting events, like HTTP requests and database queries. +To do this, it uses built-in capabilities of the instrumented frameworks like +[Diagnostic Source](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource?view=netcore-3.0), +an HTTP module for IIS, or +[IDbCommandInterceptor](https://docs.microsoft.com/en-us/dotnet/api/system.data.entity.infrastructure.interception.idbcommandinterceptor?view=entity-framework-6.2.0) for Entity Framework. +This means that for the supported technologies, there are no code changes required beyond enabling auto-instrumentation. + +The Agent automatically registers callback methods for built-in Diagnostic Source events. +With this, the supported frameworks trigger Agent code for relevant events to measure their duration and collect metadata, like DB statements, as well as HTTP related information, like the URL, parameters, and headers. +These events, called Transactions and Spans, are sent to the APM Server. +The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + +
+ +## Additional Components +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx index 088857cc4a..a08dc0df7c 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx @@ -5,3 +5,992 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import { book } from './book-variables.js' */} + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/agent-api.html) + + + + +The Elastic APM Node.js agent is a singleton. You get the agent instance by requiring either `elastic-apm-node` or `elastic-apm-node/start`. The agent is also returned by the {/* `.start()` */} method, which allows you to require and start the agent on the same line: + +```js +const apm = require('elastic-apm-node').start(...) +``` + +If you need to access the `Agent` in any part of your codebase, +you can simply require `elastic-apm-node` to access the already started singleton. +You therefore don't need to manage or pass around the started `Agent` yourself. + +
+ +## `apm.start([options])` + +Starts the Elastic APM agent for Node.js and returns itself. + + + +For the APM agent to automatically instrument Node.js modules, it must be started before those modules are loaded. See {/* Starting the agent */} for details and possible surprises with compilers/transpilers/bundlers. + + + +See the {/* Configuration documentation */} for available options. + +
+ +## `apm.isStarted()` + +_Added in: v1.5.0_ + +Use `isStarted()` to check if the agent has already started. +Returns `true` if the agent has started, +otherwise returns `false`. + +
+ +## `apm.getServiceName()` + +_Added in: v3.11.0_ + +Get the configured {/* `serviceName` */}. If a service name was not +explicitly configured, this value may have been automatically determined. +The service name is not determined until `agent.start()`, so will be `undefined` +until then. A misconfigured agent can have a `null` service name. + +
+ +## `apm.setFramework(options)` + +_Added in: v2.8.0_ + +* `options` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported: + * `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Framework name. + * `version` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Framework version. + * `overwrite` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) If set to `false`, + the {/* `frameworkName` and `frameworkVersion` */} + provided as {/* config options */} will not be overwritten. + **Default:** `true`. + +Set or change the {/* `frameworkName` */} or {/* `frameworkVersion` */} after the agent has started. +These config options can also be provided as part of the {/* regular agent configuration */}. + +
+ +## `apm.addFilter(fn)` + +_Added in: v0.1.0_ + +Use `addFilter()` to supply a filter function. + +Each filter function will be called just before data is being sent to the APM Server. +This will allow you to manipulate the data being sent, +for instance to remove sensitive information like passwords etc. +(Note: Filters added via `addFilter` are **not** applied to the "metadata" +object sent to the APM Server -- use `addMetadataFilter` instead.) + +Each filter function will be called in the order they were added, +and will receive a `payload` object as the only argument, +containing the data about to be sent to the APM Server. + +The format of the payload depends on the event type being sent. +For details about the different formats, +see the [events intake API docs](((apm-guide-ref))/api-events.html). + +The filter function is synchronous and should return the manipulated payload object. +If a filter function doesn't return any value or returns a falsy value, +the remaining filter functions will not be called and the payload **will not** be sent to the APM Server. + +Example usage: + +```js +apm.addFilter(function redactSecretHeader(payload) { + if (payload.context && + payload.context.request && + payload.context.request.headers && + payload.context.request.headers['x-secret']) { + // redact sensitive data + payload.context.request.headers['x-secret'] = '[REDACTED]' + } + + // remember to return the modified payload + return payload +}) +``` + +A set of built-in filters are added by default. +See {/* `filterHttpHeaders` */} for details. + +Though you can also use filter functions to add new contextual information to the `user` and `custom` properties, +it's recommended that you use {/* `apm.setUserContext()` */} and {/* `apm.setCustomContext()` */} for that purpose. + +
+ +## `apm.addErrorFilter(fn)` + +_Added in: v2.0.0_ + +Similar to {/* `apm.addFilter()` */}, +but the `fn` will only be called with error payloads. + +
+ +## `apm.addTransactionFilter(fn)` + +_Added in: v2.0.0_ + +Similar to {/* `apm.addFilter()` */}, +but the `fn` will only be called with transaction payloads. + +
+ +## `apm.addSpanFilter(fn)` + +_Added in: v2.0.0_ + +Similar to {/* `apm.addFilter()` */}, +but the `fn` will only be called with span payloads. + +
+ +## `apm.addMetadataFilter(fn)` + +_Added in: v3.14.0_ + +Use `addMetadataFilter(fn)` to supply a filter function for the +[metadata object](((apm-guide-ref))/api-metadata.html#api-metadata-schema) +sent to the APM Server. This will allow you to manipulate the data being +sent, for instance to remove possibly sensitive information. + +Each filter function will be called in the order they were added, and will +receive a `metadata` object as the only argument. The filter function is +synchronous and must return the manipulated object. Example usage: + +```js +apm.addMetadataFilter(function dropArgv(metadata) { + if (metadata.process && metadata.process.argv) { + delete metadata.process.argv + } + return metadata +}) +``` + +Warning: It is the responsibility of the author to ensure the returned object +conforms to the +[metadata schema](((apm-guide-ref))/api-metadata.html#api-metadata-schema) +otherwise all APM data injest will fail. A metadata filter that breaks the +metadata will result in error logging from the agent, something like: + +```text +ERROR (elastic-apm-node): APM Server transport error (400): Unexpected APM Server response +APM Server accepted 0 events in the last request +Error: validation error: 'metadata' required + Document: {"metadata":null} +``` + +
+ +## `apm.setUserContext(context)` + +_Added in: v0.1.0_ + +* `context` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Accepts the following optional properties: + * `id` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The user's ID. + * `username` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The user's username. + * `email` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The user's e-mail. + +Call this to enrich collected performance data and errors with information about the user/client. +This function can be called at any point during the request/response life cycle (i.e. while a transaction is active). + +The given `context` will be added to the active transaction. +If no active transaction can be found, +`false` is returned. +Otherwise `true`. + +It's possible to call this function multiple times within the scope of the same active transaction. +For each call, the properties of the `context` argument are shallow merged with the context previously given. + +If an error is captured, +the context from the active transaction is used as context for the captured error, +and any custom context given as the 2nd argument to {/* `apm.captureError` */} takes precedence and is shallow merged on top. + +The provided user context is stored under `context.user` in Elasticsearch on both errors and transactions. + +
+ +## `apm.setCustomContext(context)` + +_Added in: v0.1.0_ + +* `context` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Can contain any property that can be JSON encoded. + +Call this to enrich collected errors and transactions with any information that you think will help you debug performance issues or errors. +This function can be called at any point while a transaction is active (e.g. during the request/response life cycle of an incoming HTTP request). + +The provided custom context is stored under `context.custom` in APM Server pre-7.0, +or `transaction.custom` and `error.custom` in APM Server 7.0+. + +The given `context` will be added to the active transaction. +If no active transaction can be found, +`false` is returned. +Otherwise `true`. + +It's possible to call this function multiple times within the scope of the same active transaction. +For each call, the properties of the `context` argument are shallow merged with the context previously given. + +If an error is captured, +the context from the active transaction is used as context for the captured error, +and any custom context given as the 2nd argument to {/* `apm.captureError` */} takes precedence and is shallow merged on top. + + +Before using custom context, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +
+ +### `apm.setLabel(name, value[, stringify ### true])` + +_Added in: v0.1.0_ +_Renamed from `apm.setTag()` to `apm.setLabel()`: v2.10.0_ +_Added `stringify` argument in: v3.11.0_ + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), + as those characters have special meaning in Elasticsearch + +* `value` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* `stringify` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) + Defaults to `true`. When true, if a non-string `value` is given, it is + converted to a string before being sent to the APM Server. + +Set a label on the current transaction. +You can set multiple labels on the same transaction. +If an error happens during the current transaction, +it will also get tagged with the same label. + + +Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable +(as opposed to data set via {/* `apm.setCustomContext()` */}). +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +
+ +### `apm.addLabels({ [name]: value }[, stringify ### true])` + +_Added in: v1.5.0_ +_Renamed from `apm.addTags()` to `apm.addLabels()`: v2.10.0_ +_Added `stringify` argument in: v3.11.0_ + +* `labels` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Contains key/value pairs: + * `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + Any periods (`.`), asterisks (`*`), or double quotation marks (`"`) will be replaced by underscores (`_`), + as those characters have special meaning in Elasticsearch + + * `value` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) +* `stringify` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) + Defaults to `true`. When true, if a non-string `value` is given, it is + converted to a string before being sent to the APM Server. + +Add several labels on the current transaction. +You can add labels multiple times. +If an error happens during the current transaction, +it will also get tagged with the same labels. + + +Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable +(as opposed to data set via {/* `apm.setCustomContext()` */}). +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +
+ +## `apm.setGlobalLabel(name, value)` + +_Added in: v3.47.0_ + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) +* `value` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) + +Extends the {/* `globalLabels` */} configuration. It allows setting labels that are applied to all transactions. A potential use case is to specify a label with the state of your application: `'initializing' | 'available' | 'unhealthy'`. + + +Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable +(as opposed to data set via {/* `apm.setCustomContext()` */}). +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +
+ +## `apm.captureError(error[, options][, callback])` + +_Added in: v0.1.0_ + +* `error` - Can be either an [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, + a {/* message string */}, + or a {/* special parameterized message object */} + +* `options` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported: + + * `timestamp` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time when the error happened. + Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. + Sub-millisecond precision can be achieved using decimals. + If not provided, + the current time will be used + + * `message` - If the `error` argument is an [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, + it's possible to use this option to supply an additional message string that will be stored along with the error message under `log.message` + + * `user` - See {/* metadata section */} for details about this option + + * `custom` - See {/* metadata section */} for details about this option + + * `request` [``](https://nodejs.org/api/http.html#http_class_http_incomingmessage) You can associate an error with information about the incoming request to gain additional context such as the request url, headers, and cookies. + However, in most cases, the agent will detect if an error was in response to an http request and automatically add the request details for you. + See {/* http requests section */} for more details. + + * `response` [``](https://nodejs.org/api/http.html#http_class_http_serverresponse) You can associate an error with information about the http response to get additional details such as status code and headers. + However, in most cases, the agent will detect if an error occured during an http request and automatically add response details for you. + See {/* http responses section */} for more details. + + * `handled` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Adds additional context to the exception to show + whether the error is handled or uncaught. Unhandled errors are immediately + flushed to APM server, in case the application is about the crash. + **Default:** `true`. + + * `labels` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Add additional context with labels, these labels will be added to the error along with the labels from the current transaction. + See the {/* `apm.addLabels()` */} method for details about the format. + + * `captureAttributes` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Whether to include properties on the given [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object in the data sent to the APM Server (as `error.exception.attributes`). **Default:** `true`. + + * `skipOutcome` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Whether to skip setting the outcome value for the current span to `failure`. See {/* Span outcome */} for more information. **Default:** `false`. + + * `parent` {/* Transaction | Span */} | `null` - A Transaction or Span instance to make the parent of this error. If not given (or `undefined`), then the current span or transaction will be used. If `null` is given, then no span or transaction will be used. _(Added in v3.33.0.)_ + +* `callback` - Will be called after the error has been sent to the APM Server. + It will receive an `Error` instance if the agent failed to send the error, + and the id of the captured error. + +Send an error to the APM Server: + +```js +apm.captureError(new Error('boom!')) +``` + +
+ +### Message strings + +Instead of an `Error` object, +you can log a plain text message: + +```js +apm.captureError('Something happened!') +``` + +This will also be sent as an error to the APM Server, +but will not be associated with an exception. + +
+ +### Parameterized message object + +Instead of an `Error` object or a string, +you can supply a special parameterized message object: + +```js +apm.captureError({ + message: 'Could not find user %s with id %d in the database', + params: ['Peter', 42] +}) +``` + +This makes it possible to better group error messages that contain variable data like ID's or names. + +
+ +### Metadata + +To ease debugging it's possible to send some extra data with each error you send to the APM Server. +The APM Server intake API supports a lot of different metadata fields, +most of which are automatically managed by the Elastic APM Node.js Agent. +But if you wish you can supply some extra details using `user` or `custom`. +For more details on the properties accepted by the events intake API see the [events intake API docs](((apm-guide-ref))/api-events.html). + +To supply any of these extra fields, +use the optional options argument when calling `apm.captureError()`. + +Here are some examples: + +```js +// Sending some extra details about the user +apm.captureError(error, { + user: { + id: 'unique_id', + username: 'foo', + email: 'foo@example.com' + } +}) + +// Sending some arbitrary details using the `custom` field +apm.captureError(error, { + custom: { + some_important_metric: 'foobar' + } +}) +``` + +To supply per-request metadata to all errors captured in one central location, +use {/* `apm.setUserContext()` */} and {/* `apm.setCustomContext()` */}. + +
+ +### HTTP requests + +Besides the options described in the {/* metadata section */}, +you can use the `options` argument to associate the error with an HTTP request: + +```js +apm.captureError(err, { + request: req // an instance of http.IncomingMessage +}) +``` + +This will log the URL that was requested, +the HTTP headers, +cookies and other useful details to help you debug the error. + +In most cases, this isn't needed, +as the agent is pretty smart at figuring out if your Node.js app is an HTTP server and if an error occurred during an incoming request. +In which case it will automate this processes for you. + +
+ +### HTTP responses + +Besides the options described in the {/* metadata section */}, +you can use the `options` argument to associate the error with an HTTP response: + +```js +apm.captureError(err, { + response: res // an instance of http.ServerResponse +}) +``` + +This will log the response status code, +headers and other useful details to help you debug the error. + +In most cases, this isn't needed, +as the agent is pretty smart at figuring out if your Node.js app is an HTTP server and if an error occurred during an incoming request. +In which case it will automate this processes for you. + +
+ +## `apm.middleware.connect()` + +_Added in: v0.1.0_ + +Returns a middleware function used to collect and send errors to the APM Server. + +```js +const apm = require('elastic-apm-node').start() +const connect = require('connect') + +const app = connect() + +// your regular middleware: +app.use(...) +app.use(...) + +// your main HTTP router +app.use(function (req, res, next) { + throw new Error('Broke!') +}) + +// add Elastic APM in the bottom of the middleware stack +app.use(apm.middleware.connect()) + +app.listen(3000) +``` + + +`apm.middleware.connect` _must_ be added to the middleware stack _before_ any other error handling middleware functions or there's a chance that the error will never get to the agent. + + +
+ +## `apm.startTransaction([name][, type][, subtype][, action][, options])` + +_Added in: v0.1.0_ +_Transaction `subtype` and `action` deprecated in: v3.25.0_ + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the transaction. + You can always set this later via {/* `transaction.name` or `apm.setTransactionName()` */}. + **Default:** `unnamed` + +* `type` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The type of the transaction. + You can always set this later via {/* `transaction.type` */}. + +* `subtype` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The subtype of the transaction. + You can alternatively set this via {/* `transaction.subtype` */}. + The transaction `subtype` field is deprecated: it is not used and will be + removed in the next major version. + +* `action` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The action of the transaction. + You can alternatively set this via {/* `transaction.action` */}. + The transaction `action` field is deprecated: it is not used and will be removed + in the next major version. + +* `options` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported: + + * `startTime` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time when the transaction started. + Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. + Sub-millisecond precision can be achieved using decimals. + If not provided, + the current time will be used + + * `childOf` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) A W3C trace-context "traceparent" string, typically received from a remote service call. + + * `tracestate` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) A W3C trace-context "tracestate" string. + + * `links` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Span links. + A transaction can refer to zero or more other transactions or spans (separate + from its parent). Span links will be shown in the Kibana APM app trace view. + The `links` argument is an array of objects with a single "context" field + that is a `Transaction`, `Span`, or W3C trace-context 'traceparent' string. + For example: `apm.startTransaction('aName', { links: [{ context: anotherSpan }] })`. + +Start a new transaction. + +Use this function to create a custom transaction. +Note that the agent will do this for you automatically whenever your application receives an incoming HTTP request. +You only need to use this function to create custom transactions. + +There's a special `type` called `request` which is used by the agent for the transactions automatically created when an incoming HTTP request is detected. + +See the {/* Transaction API */} docs for details on how to use custom transactions. + +
+ +## `apm.endTransaction([result][, endTime])` + +_Added in: v0.1.0_ + +* `result` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Describes the result of the transaction. + This is typically the HTTP status code, + or e.g. "success" or "failure" for a background task + +* `endTime` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time when the transaction ended. + Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. + Sub-millisecond precision can be achieved using decimals. + If not provided, + the current time will be used + +Ends the active transaction. +If no transaction is currently active, +nothing happens. + +Note that the agent will do this for you automatically for all regular HTTP transactions. +You only need to use this function to end custom transactions created by {/* `apm.startTransaction()` */} or if you wish the end a regular transaction prematurely. + +Alternatively you can call {/* `end()` */} directly on an active transaction object. + +
+ +## `apm.currentTransaction` + +_Added in: v1.9.0_ + +Get the currently active transaction, +if used within the context of a transaction. + + +If there's no active transaction available, +`null` will be returned. + + +
+ +## `apm.currentSpan` + +_Added in: v2.0.0_ + +Get the currently active span, +if used within the context of a span. + + +If there's no active span available, +`null` will be returned. + + +
+ +## `apm.currentTraceparent` + +_Added in: v2.9.0_ + +Get the serialized traceparent string of the current transaction or span. + + +If there's no active transaction or span available, +`null` will be returned. + + +
+ +## `apm.setTransactionName(name)` + +_Added in: v0.1.0_ + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Set or overwrite the name of the current transaction. + +If you use a supported router/framework the agent will automatically set the transaction name for you. + +If you do not use Express, hapi, koa-router, Restify, or Fastify or if the agent for some reason cannot detect the name of the HTTP route, +the transaction name will default to `METHOD unknown route` (e.g. `POST unknown route`). + +Read more about naming routes manually in the {/* Get started with a custom Node.js stack */} article. + +
+ +## `apm.startSpan([name][, type][, subtype][, action][, options])` + +_Added in: v1.1.0_ + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the span. + You can alternatively set this via {/* `span.name` */}. + **Default:** `unnamed` + +* `type` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The type of the span. + You can alternatively set this via {/* `span.type` */}. + +* `subtype` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The subtype of the span. + You can alternatively set this via {/* `span.subtype` */}. + +* `action` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The action of the span. + You can alternatively set this via {/* `span.action` */}. + +* `options` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported: + + * `startTime` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time when the span started. + Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. + Sub-millisecond precision can be achieved using decimals. + If not provided, + the current time will be used + + * `exitSpan` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Make an "exit span". + Exit spans represent outgoing communication. They are used to create a node + in the [Service Map](((kibana-ref))/service-maps.html) and a downstream service + in the [Dependencies Table](((kibana-ref))/dependencies.html). The provided subtype + will be used as the downstream service name. + + * `links` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Span links. + A span can refer to zero or more other transactions or spans (separate from + its parent). Span links will be shown in the Kibana APM app trace view. The + `links` argument is an array of objects with a single "context" field that is a + `Transaction`, `Span`, or W3C trace-context 'traceparent' string. For example: + `apm.startSpan('aName', { links: [{ context: anotherSpan }] })`. + +Start and return a new custom span associated with the current active transaction. +This is the same as getting the current transaction with `apm.currentTransaction` and, +if a transaction was found, +calling `transaction.startSpan(name, type, options)` on it. + +When a span is started it will measure the time until {/* `span.end()` */} is called. + +See {/* Span API */} docs for details on how to use custom spans. + + +If there's no active transaction available, +`null` will be returned. + + +
+ +## `apm.handleUncaughtExceptions([callback])` + +_Added in: v0.1.0_ + +By default, the agent will terminate the Node.js process when an uncaught exception is detected. +Use this function if you need to run any custom code before the process is terminated. + +```js +apm.handleUncaughtExceptions(function (err) { + // Do your own stuff... and then exit: + process.exit(1) +}) +``` + +The callback is called **after** the event has been sent to the APM Server with the following arguments: + +* `err` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) the captured exception + +This function will also enable the uncaught exception handler if it was disabled using the {/* `captureExceptions` */} configuration option. + +If you don't specify a callback, +the node process is terminated automatically when an uncaught exception has been captured and sent to the APM Server. + +[It is recommended](https://nodejs.org/api/process.html#process_event_uncaughtexception) that you don't leave the process running after receiving an uncaught exception, +so if you are using the optional callback, +remember to terminate the node process. + +
+ +## `apm.flush([callback])` + +_Added in: v0.12.0_ + +```js +// with node-style callback +apm.flush(function (err) { + // Flush complete +}) + +// with promises +apm.flush().then(function () { + // Flush complete +}).catch(function (err) { + // Flush returned an error +}) + +// inside of an async function +try { + await apm.flush() + // Flush complete +} catch (err) { + // Flush returned an error +} +``` + +Manually end the active outgoing HTTP request to the APM Server. +The HTTP request is otherwise ended automatically at regular intervals, +controlled by the {/* `apiRequestTime` and `apiRequestSize` */} config options. + +If an optional `callback` is provided as the first argument to this method, it will call `callback(flushErr)` when complete. +If no `callback` is provided, then a `Promise` will be returned, which will either resolve with `void` or reject with `flushErr`. + +The callback is called (or the `Promise` resolves if no `callback` argument is provided) **after** the active HTTP request has ended. +The callback is called even if no HTTP request is currently active. + +
+ +## `apm.lambda([type, ]handler)` + +_Added in: v1.4.0_ + +```js +exports.hello = apm.lambda(function (event, context, callback) { + callback(null, `Hello, ${payload.name}!`) +}) +``` + +Manually instrument an AWS Lambda function to form a transaction around each execution. +Optionally, a type may also be provided to group lambdas together. By default, +"lambda" will be used as the type name. + +Read more lambda support in the {/* Lambda */} article. + +
+ +## `apm.addPatch(modules, handler)` + +_Added in: v2.7.0_ + +* `modules` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + Name of module(s) to apply the patch to, when required. + +* `handler` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) | [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + Must be a patch function or a path to a module exporting a patch function + + * `exports` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The original export object of the module + * `agent` - The agent instance to use in the patch function + * `options` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) The following options are supported: + * `version` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [``](https://developer.mozilla.org/en-US/docs/Glossary/Undefined) The module version, if applicable. + * `enabled` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) A flag indicating if the instrumentation is enabled. + Any module patch can be disabled, by module name, with {/* `disableInstrumentations` */}. + +Register a module patch to apply on intercepted `require` calls. + +A module can have any number of patches and will be applied in the order they are added. + +```js +apm.addPatch('timers', (exports, agent, { version, enabled }) => { + const setTimeout = exports.setTimeout + exports.setTimeout = (fn, ms) => { + const span = agent.startSpan('set-timeout') + return setTimeout(() => { + span.end() + fn() + }, ms) + } + + return exports +}) + +// or ... + +apm.addPatch(['hapi', '@hapi/hapi'], (exports, agent, { version, enabled }) => { + const setTimeout = exports.setTimeout + exports.setTimeout = (fn, ms) => { + const span = agent.startSpan('set-timeout') + return setTimeout(() => { + span.end() + fn() + }, ms) + } + + return exports +}) + +// or ... + +apm.addPatch('timers', './timer-patch') +``` + +
+ +## `apm.removePatch(modules, handler)` + +_Added in: v2.7.0_ + +Removes a module patch. +This will generally only be needed when replacing an existing patch. +To _disable_ instrumentation while keeping context propagation support, see {/* `disableInstrumentations`. */} + +```js +apm.removePatch('timers', './timers-patch') + +// or ... + +apm.removePatch(['timers'], './timers-patch') + +// or ... + +apm.removePatch('timers', timerPatchFunction) +``` + +
+ +## `apm.clearPatches(modules)` + +_Added in: v2.7.0_ + +Clear all patches for the given module. +This will generally only be needed when replacing an existing patch. +To _disable_ instrumentation while keeping context propagation support, see {/* `disableInstrumentations` */}. + +```js +apm.clearPatches('timers') + +// or ... + +apm.clearPatches(['timers']) +``` + +
+ +## `apm.currentTraceIds` + +_Added in: v2.17.0_ + +`apm.currentTraceIds` produces an object containing `trace.id` and either `transaction.id` or `span.id` when a current transaction or span is available. +When no transaction or span is available it will return an empty object. +This enables {/* log correlation */} to APM traces with structured loggers. + +```js +{ + "trace.id": "abc123", + "transaction.id": "abc123" +} +// or ... +{ + "trace.id": "abc123", + "span.id": "abc123" +} +``` + +
+ +## `apm.registerMetric(name[, labels], callback)` + + +* `name` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + Name of the metrics. + +* `labels` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Contains key/value pairs. + Optional labels. Omittable. + +* `callback` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) + Must be a function that returns the current metric value. + +Register a metric callback. + +Take care not to use the names of {/* built-in metrics */}. + +```js +apm.registerMetric( 'ws.connections' , () => { + return wss.clients.size; +}) + +// or, to additionally label the metric with "module: 'ws'": + +apm.registerMetric( 'ws.connections' , {module : 'ws'}, () => { + return wss.clients.size; +}) + +``` + +
+ +## `apm.setTransactionOutcome(outcome)` + +_Added in: v3.12.0_ + +* `outcome` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + +Will set the outcome property on the _current_ transaction. + +See the {/* Transaction Outcome docs */} for more information. + +
+ +## `apm.setSpanOutcome(outcome)` + +_Added in: v3.12.0_ + +* `outcome` [``](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) + +Will set the outcome property on the _current_ span. + +See the {/* Span Outcome docs */} for more information. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx index 69ddf36747..49dcb9b537 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx @@ -5,3 +5,25 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/advanced-setup.html). + + + + +Use the following pages to configure the APM Agent. + +* {/* Configuring the agent */} + * {/* Agent configuration object */} + * {/* Agent configuration file */} +* \<\> + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx index 79d58b20d2..a2c9db0106 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx @@ -5,3 +5,154 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +{/* import SharedSetUpFilterSensitiveInfo from './transclusion/shared-set-up/filter-sensitive-info.mdx' */} +{/* import SharedSetUpCompatibilityLink from './transclusion/shared-set-up/compatibility-link.mdx' */} +{/* import SharedSetUpTroubleshootingLink from './transclusion/shared-set-up/troubleshooting-link.mdx' */} + +export let framework = "Azure Functions" + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/azure-functions.html) + + + + +The Node.js APM Agent can trace function invocations in an [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/) app. + +
+ +## Prerequisites + +You need an APM Server to send APM data to. Follow the +[APM Quick start](((apm-guide-ref))/apm-quick-start.html) if you have not set one up +yet. You will need your **APM server URL** and an APM server **secret token** (or +**API key**) for configuring the APM agent below. + +You will also need an Azure Function app to monitor. If you do not have an +existing one, you can follow [this Azure guide](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-cli-node#create-supporting-azure-resources-for-your-function) +to create one. + + + +If you use `func init --javascript ...` as suggested in this Azure guide, +then it is recommended that you **uninstall** the `azure-functions-core-tools` +dependency by running `npm uninstall azure-functions-core-tools` and +[install it separately](https://github.com/Azure/azure-functions-core-tools#installing). +Having `azure-functions-core-tools` as a "devDependency" in your package.json +will result in unreasonably large deployments that will be very slow to publish +and will run your Azure Function app VM out of disk space. + + + +You can also take a look at and use this [Azure Functions example app with Elastic APM already integrated](https://github.com/elastic/apm-agent-nodejs/tree/main/examples/an-azure-function-app/). + +
+ +## Step 1: Add the APM agent dependency + +Add the `elastic-apm-node` module as a dependency of your application: + +```bash +npm install elastic-apm-node --save # or 'yarn add elastic-apm-node' +``` + +## Step 2: Start the APM agent + +For the APM agent to instrument Azure Functions, it needs to be started when the +Azure host starts its Node.js worker processes. The best way to do so is by +using an app-level entry point (support for this was added for Node.js Azure +Functions [here](https://github.com/Azure/azure-functions-nodejs-worker/issues/537)). + +1. Create a module to start the APM agent. For example, a file at the root of your repository named "initapm.js": + + ```javascript + // initapm.js + require('elastic-apm-node').start({ + [^1] + }) + ``` + [^1]: Optional {/* configuration options */} can be added here. + +1. Add a "main" entry to your package.json pointing to the app init file. + + ```json + ... + "main": "initapm.js", + ... + ``` + + If your application already has a "main" init file, you can instead add the + `require('elastic-apm-node').start()` to top of that file. + +## Step 3: Configure the APM agent + +The APM agent can be {/* configured */} with options to the +`.start()` method or with environment variables. Using environment variables +allows one to use [application settings in the Azure Portal](https://learn.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings?tabs=portal#settings) which allows hiding values and updating settings +without needing to re-deploy code. + +Open _Configuration > Application settings_ for your Function App in the Azure Portal +and set: + +```yaml +ELASTIC_APM_SERVER_URL: +ELASTIC_APM_SECRET_TOKEN: +``` + +For example: + +{/* ![Configuring the APM Agent in the Azure Portal](images/azure-functions/-azure-functions-configuration.png) */} + +For local testing via `func start` you can set these environment variables in +your terminal, or in the "local.settings.json" file. See the {/* agent configuration guide */} for full details on supported +configuration variables. + +## Step 4: (Re-)deploy your Azure Function app + +```bash +func azure functionapp publish +``` + +Now, when you invoke your Azure Functions, you should see your application +show up as a Service in the APM app in Kibana and see APM transactions for +function invocations. Tracing data is forwarded to APM server after a period +of time, so allow a minute or so for data to appear. + +
+ +## Limitations + +This instrumentation does not send an APM transaction or error to APM server when +a handler has an `uncaughtException` or `unhandledRejection`. +The Azure Functions Node.js reference [has a section](https://learn.microsoft.com/en-ca/azure/azure-functions/functions-reference-node#use-async-and-await) with best practices for avoiding these cases. + +Azure Functions instrumentation currently does _not_ collect system metrics in +the background because of a concern with unintentionally increasing Azure +Functions costs (for Consumption plans). + +
+ +## Filter sensitive information + +{/* */} + +
+ +## Compatibility + +{/* */} + +
+ +## Troubleshooting + +{/* */} diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx index 0c424b440f..38fa62391d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx index 2d071ee334..8dab4e68e5 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx @@ -5,3 +5,172 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/performance-tuning.html) + + + + +The Node.js APM agent offers a variety of {/* configuration options */}, +some of which can have a significant impact on performance. Areas where APM +agent overhead might be seen are: CPU, memory, network, latency, and storage. +This document discusses the options most significant for performance tuning the +APM agent. + +
+ +## Sample rate + +The _sample rate_ is the percentage of incoming requests that are recorded and +sent to the APM Server. This is controlled by the +{/* `transactionSampleRate` */} configuration option. By +default _all_ requests are traced (`transactionSampleRate: 1.0`). + +The amount of work the APM agent needs to do, generally scales linearly with +the number of traced requests. Therefore, the sample rate impacts CPU, memory, +network, and storage overhead. + +Applications with a high request rate and/or many spans per incoming request +may want to lower the the sampling rate. For example, see the example below +to trace 20% of incoming requests. Note that incoming HTTP requests that are +part of a {/* distributed trace */} already have the sampling +decision made -- the `traceparent` header includes a +[sampled flag](https://w3c.github.io/trace-context/#sampled-flag). In these cases +the `transactionSampleRate` setting will not apply. + +```js +require('elastic-apm-node').start({ + transactionSampleRate: 0.2 // sample 20% of incoming requests +}) +``` + +
+ +## Stack Traces + +When the APM agent captures an error, it records its stack trace for later +analysis and viewing. Optionally, the APM agent can also record a stack trace +for captured **spans**. Stack traces can have a significant impact on CPU and +memory usage of the agent. There are several settings to adjust how they are +used. + +
+ +### Span Stack Traces + +The {/* `spanStackTraceMinDuration` */} configuration +option controls if stack traces are never captured for spans (the +default), always captured for spans, or only captured for spans that are longer +than a given duration. In a complex application, a traced request may capture +many spans. Capturing and sending a stack trace for every span can result in +significant CPU and memory usage. + +It is because of the possibility of this CPU overhead that the APM Agent +disables stack trace collection for _spans_ by default. Unfortunately, even +the capturing of raw stack trace data at span creation and then throwing that +away for fast spans can have significant CPU overhead for heavily loaded +applications. Therefore, care must be taken before using `spanStackTraceMinDuration`. + +
+ +### Stack Trace Source Lines + +If you want to keep span stack traces enabled for context, +the next thing to try is adjusting how many source lines are reported for each stack trace. +When a stack trace is captured, +the agent will also capture several lines of source code around each stack frame location in the stack trace. + +The are four different settings to control this behaviour: + +- {/* `sourceLinesErrorAppFrames` */} +- {/* `sourceLinesErrorLibraryFrames` */} +- {/* `sourceLinesSpanAppFrames` */} +- {/* `sourceLinesSpanLibraryFrames` */} + +Source line settings are divided into app frames representing your app code and library frames representing the code of your dependencies. +App and library categories are both split into error and span groups. +Spans, +by default, +do not capture source lines. +Errors, +by default, +will capture five lines of code around each stack frame. + +Source lines are cached in-process. +In memory-constrained environments, +the source line cache may use more memory than desired. +Turning the limits down will help prevent excessive memory use. + +
+ +### Stack Frame Limit + +The {/* `stackTraceLimit` */} configuration option controls how +many stack frames are captured when producing an `Error` instance of any kind. +A large value may impact CPU and memory overhead of the agent. + +
+ +### Error Log Stack Traces + +Most stack traces recorded by the agent will point to where the error was instantiated, +not where it was identified and reported to the agent with {/* `captureError` */}. +For this reason, +the agent also has the {/* `captureErrorLogStackTraces` */} setting to enable capturing an additional stack trace pointing to the place an error was reported to the agent. +By default, +it will only capture the stack trace to the reporting point when {/* `captureError` */} is called with a string message. + +Setting this to `always` will increase memory and bandwidth usage, +so it helps to consider how frequently the app may capture errors. + +
+ +## Spans + +The {/* `transactionMaxSpans` */} setting limits the number of spans which may be recorded within a single transaction before remaining spans are dropped. + +Spans may include many things such as a stack trace and context data. +Limiting the number of spans that may be recorded will reduce memory usage. + +Reducing max spans could result in loss of useful data about what occurred within a request, +if it is set too low. + +An alternative to limiting the maximum number of spans can be to drop spans with a very short duration, as those might not be that relevant. + +This, however, both reduces the amount of storage needed to store the spans in Elasticsearch, and the bandwidth needed to transport the data to the APM Server from the instrumented application. + +This can be implemented by providing a span-filter: + +```js +agent.addSpanFilter(payload => { + return payload.duration < 10 ? null : payload +}) +``` + + +Using a span filter does not reduce the load of recording the spans in your application, but merely filters them out before sending them to the APM Server. + + +
+ +## Max queue size + +The APM agent uses a persistent outgoing HTTP request (periodically refreshed) +to stream data to the APM Server. If either the APM agent cannot keep up with +events (transactions, spans, errors, and metricsets) from the application or +if the APM Server is slow or not responding, then the agent will buffer events. +If the buffer exceeds {/* `maxQueueSize` */}, then events are dropped to limit +memory usage of the agent. + +A lower value for `maxQueueSize` will decrease the heap overhead (and possibly +the CPU usage) of the agent, while a higher value makes it less likely to lose +events in case of a temporary spike in throughput. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx index 9ceed95e90..741116b0d6 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx @@ -5,3 +5,179 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/supported-technologies.html) + + + + +The Elastic APM Node.js Agent automatically instruments various APIs in Node.js core and third-party frameworks and packages. This page lists all supported technologies and version ranges. + +
+ +## Node.js versions + +Support for the Elastic APM Node.js agent follows the [support schedule of Node.js itself](https://nodejs.org/en/about/releases/) +to the end-of-life period of each version after its maintenance term. +Versions of Node.js past their end-of-life date are not supported. + +image::./images/node_release_schedule.svg[Node.js release schedule] + +The current APM agent version (3.x) works with Node.js versions back to v8.6. We will only break support for older Node.js versions with a major version release of the APM agent. + +
+ +## ECMAScript Modules (ESM) + +Beginning with version v3.48.0, the Elastic APM Node.js agent includes +_limited and experimental_ support for instrumenting +[ECMAScript module imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), +i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). +See the {/* ECMAScript module support */} document for details. + +Note: If you are using TypeScript or JavaScript that is _compiled/translated/transpiled to CommonJS-using JavaScript_ via tools like Babel, Webpack, esbuild, etc., then using `import ...` in your source code is fine. To ensure your compiler is generating JS that uses CommonJS imports, use the following settings: + +- For TypeScript, use [`"module": "commonjs"` in your "tsconfig.json"](https://www.typescriptlang.org/tsconfig#module) (a [complete tsconfig.json example](https://github.com/tsconfig/bases/blob/main/bases/node16.json)). +- For Babel, use [`"modules": "commonjs"` in your Babel config](https://babeljs.io/docs/en/babel-preset-env#modules) ([for example](https://github.com/elastic/apm-agent-nodejs/blob/main/test/babel/.babelrc)). +- For Webpack, use `target: 'node', externalsPresets: { node: true }` in your "webpack.config.js". +- For esbuild, use `--platform=node --target=node...` options to `esbuild` ([for example](https://github.com/elastic/apm-agent-nodejs/blob/main/examples/esbuild/package.json#L7)). + +
+ +## Elastic Stack Compatibility + +{/* See the APM agent compatibility table: https://www.elastic.co/guide/en/apm/guide/current/agent-server-compatibility.html */} + +This agent is compatible with [APM Server](((apm-guide-ref))) v6.6 and above. + +
+ +## Frameworks + +Though you can use Elastic APM {/* with any Node.js framework */}, +we automate a few things for the most popular Node.js modules. +These are the frameworks that we officially support: + +| Framework | Version | Note | +|---|---|---| +| {/* AWS Lambda */} | N/A | | +| {/* Azure Functions */} | ~4 | See [the guide on Azure Functions runtime versions](https://learn.microsoft.com/en-ca/azure/azure-functions/set-runtime-version). | +| {/* Express */} | ^4.0.0 | | +| {/* Fastify */} | >=1.0.0 | See also [Fastify's own LTS documentation](https://www.fastify.io/docs/latest/Reference/LTS/) | +| {/* @hapi/hapi */} | >=17.9.0 \<22.0.0 | | +| {/* hapi */} | >=9.0.0 \<19.0.0 | Deprecated. No longer tested. | +| {/* Koa */} via koa-router or @koa/router | >=5.2.0 \<13.0.0 | Koa doesn't have a built in router, so we can't support Koa directly since we rely on router information for full support. We currently support the most popular Koa router called [koa-router](https://github.com/koajs/koa-router). | +| {/* Next.js */} | >=11.1.0 \<13.3.0 | (Technical Preview) This instruments Next.js routing to name transactions for incoming HTTP transactions; and reports errors in user pages. It supports the Next.js production server (`next start`) and development server (`next dev`). See the {/* Getting Started document */}. | +| {/* Restify */} | >=5.2.0 \<12.0.0 | | + +
+ +## OpenTelemetry + +The Node.js Elastic APM agent supports usage of the OpenTelemetry Tracing API +via its {/* OpenTelemetry bridge */}. As well, it instruments the OpenTelemetry +Metrics API and Metrics SDK to allow {/* usage of the OpenTelemetry Metrics API */}. + +| Framework | Version | +|---|---| +| {/* @opentelemetry/api */} | >=1.0.0 \<1.5.0 | +| [@opentelemetry/sdk-metrics](https://www.npmjs.com/package/@opentelemetry/sdk-metrics) | >=1.11.0 \<2 | + +
+ +## Custom Transactions + +By default transactions are named based on their matched HTTP route if the framework used is listed above. +These modules override that behavior to give better insights into specialized HTTP servers: + +| Module | Version | Note | +|---|---|---| +| [express-graphql](https://www.npmjs.com/package/express-graphql) | >=0.6.1 \<0.13.0 | Will name all transactions by the GraphQL query name. There is a [known issue with node \<10.4](https://github.com/elastic/apm-agent-nodejs/issues/2516). This module is deprecated and is no longer tested. | +| [apollo-server-express](https://www.npmjs.com/package/apollo-server-express) | >=2.0.4 \< | Will name all transactions by the GraphQL query name. Versions before 2.9.6 are no longer tested. | +| [@apollo/server](https://www.npmjs.com/package/@apollo/server) | >=4.0. | Will name all transactions by the GraphQL query name | + +
+ +## Tracing and Instrumentation + +The Node.js agent will automatically instrument the following modules to give you detailed performance metrics: + +| Module | Version | Note | +|---|---|---| +| [aws-sdk](https://www.npmjs.com/package/aws-sdk) | >=2.858.0 \<3 | Will instrument SQS send/receive/delete messages, all S3 methods, all DynamoDB methods, and the SNS publish method | +| [@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3) | >=3.15.0 \<4 | Will instrument all S3 methods | +| [cassandra-driver](https://www.npmjs.com/package/cassandra-driver) | >=3.0.0 \<5 | Will instrument all queries | +| [elasticsearch](https://www.npmjs.com/package/elasticsearch) | >=8.0.0 | Will instrument all queries | +| [@elastic/elasticsearch](https://www.npmjs.com/package/@elastic/elasticsearch) | >=7.0.0 \<9.0.0 | Will instrument all queries | +| [graphql](https://www.npmjs.com/package/graphql) | >=0.7.0 \<17 | Will instrument all queries | +| [handlebars](https://www.npmjs.com/package/handlebars) | * | Will instrument compile and render calls | +| [jade](https://www.npmjs.com/package/jade) | >=0.5.6 | Will instrument compile and render calls; Deprecated. No longer tested. Use pug. | +| [pug](https://www.npmjs.com/package/pug) | >=0.1.0 | Will instrument compile and render calls | +| [ioredis](https://www.npmjs.com/package/ioredis) | >=2.0.0 \<6.0.0 | Will instrument all queries | +| [memcached](https://www.npmjs.com/package/memcached) | >=2.2.0 | Will instrument all commands. | +| [mongodb-core](https://www.npmjs.com/package/mongodb-core) | >=1.2.19 \<4 | Will instrument all queries. A lot of higher level MongoDB modules use mongodb-core, so those should be supported as well. | +| [mongodb](https://www.npmjs.com/package/mongodb) | >=2.0.0 \<3.3.0 | Supported via mongodb-core | +| [mongodb](https://www.npmjs.com/package/mongodb) | >=3.3.0 \<6 | Will instrument all queries | +| [mongojs](https://www.npmjs.com/package/mongojs) | >=1.0.0 \<2.7.0 | Supported via mongodb-core | +| [mongoose](https://www.npmjs.com/package/mongoose) | >=4.0.0 \<5.7.0 | Supported via mongodb-core | +| [mysql](https://www.npmjs.com/package/mysql) | ^2.0.0 | Will instrument all queries | +| [mysql2](https://www.npmjs.com/package/mysql2) | >=1.0.0 \<4.0.0 | Will instrument all queries | +| [pg](https://www.npmjs.com/package/pg) | >=4.0.0 \<9.0.0 | Will instrument all queries | +| [redis](https://www.npmjs.com/package/redis) | >=2.0.0 \<5.0.0 | Will instrument all queries | +| [tedious](https://www.npmjs.com/package/tedious) | >=1.9 \<17.0.0 | (Excluding v4.0.0.) Will instrument all queries | +| [undici](https://www.npmjs.com/package/undici) | >=4.7.1 \<6 | Will instrument undici HTTP requests, except HTTP CONNECT. Requires node v14.17.0 or later, or the user to have installed the ['diagnostics_channel' polyfill](https://www.npmjs.com/package/diagnostics_channel). | +| [ws](https://www.npmjs.com/package/ws) | >=1.0.0 \<8.0.0 | Will instrument outgoing WebSocket messages | + +
+ +## Better Stack Traces + +The APM agent {/* can be configured */} to capture +span stack traces, to show where in your code a span (e.g. for a database query) +was initiated. + +Given the async nature of Node.js, it's not possible for the APM agent to see +further back than the last async boundary. Modules that happen to have an async +boundary between a call from your application code and the action that leads +to an APM span will limit the utility of these span stack traces. + +The modules listed below are those that the APM agent instruments to provide +more useful span stack traces -- ones that point to your application code -- +when enabled. + +If you don't see your own code in spans, +please create a new topic in the [Elastic APM discuss forum](https://discuss.elastic.co/c/apm) and include information about your dependencies. + +| Module | Version | Note | +|---|---|---| +| [knex](https://www.npmjs.com/package/knex) | >=0.10.0 \<3.0.0 | Provides better span stack traces for 'pg' and 'mysql' spans. Instrumentation of Knex >=0.95.0 is not supported when using the deprecated {/* `contextManager=patch` */} configuration option. | + +
+ +## Continuity + +The Elastic APM agent monitors async operations in your Node.js application to maintain awareness of which request is the active request at any given time. +Certain modules can interfere with this monitoring if not handled properly. + +Below is a list of modules known to cause issues with this monitoring. +The versions listed are the versions we support. +If you use an unsupported version you might experience missing spans. +This does not impact the stability of your application in any way - only the collected metrics. + +If you do experience missing spans in your performance metrics, +please create a new topic in the [Elastic APM discuss forum](https://discuss.elastic.co/c/apm) and include information about your dependencies and what data is missing. + +| Module | Version | Note | +|---|---|---| +| [bluebird](https://www.npmjs.com/package/bluebird) | >=2.0.0 \<4.0.0 | | +| [generic-pool](https://www.npmjs.com/package/generic-pool) | ^2.0.0 \|\| ^3.1.0 | +| Used by a lot of database modules like for instance "pg" | [express-queue](https://www.npmjs.com/package/express-queue) | >=0.0.11 \<1.0.0 | diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx index fd9aadf076..f8d7ab6c39 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx @@ -5,3 +5,44 @@ title: Node.js # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +export let env_github = false + + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/nodejs/current/intro.html) + + + + +The Elastic APM Node.js Agent sends performance metrics and errors to the APM Server. +It has built-in support for the most popular frameworks and routers, +as well as a simple API which allows you to instrument any application. + +
+ +## How does the Agent work? + +The agent auto-instruments supported frameworks and records interesting events, +like HTTP requests and database queries. To do this, it patches modules as they are loaded to capture when module functions and callbacks are called. Additionally, there are some cases where a module will be patched to allow tracing context to be propagated through the asynchronous continuation. +This means that for the supported technologies, there are no code changes required. + +The Agent automatically links module function calls to callback calls to measure their duration and metadata (like the DB statement), +as well as HTTP related information (like the URL, parameters, and headers). + +These events, called Transactions and Spans, are sent to the APM Server. +The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + +
+ +## Additional Components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx index e908d3e62d..db2ab26b6f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx @@ -5,3 +5,5 @@ title: Collect metrics # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx index 10d1f49a9a..4e6bf06560 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx @@ -5,3 +5,5 @@ title: Limitations # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx index a1249f4d15..6f5f5f2d6b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx @@ -5,3 +5,5 @@ title: OpenTelemetry API/SDK with Elastic APM agents # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx index c017d16548..3e39acfb7e 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx @@ -5,3 +5,5 @@ title: OpenTelemetry native support # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx index 31e08d00d7..83b506fb80 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx @@ -5,3 +5,5 @@ title: Other execution environments # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx index 15b6bc35b4..af2f26f632 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx @@ -5,3 +5,5 @@ title: Resource attributes # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx index 423eae47b6..de8fbc01c0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx @@ -5,3 +5,5 @@ title: OpenTelemetry # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx index cbff9a50de..bf231b6e5b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx @@ -5,3 +5,657 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/php) + + + +
+ +The public API of the Elastic APM PHP agent lets you +customize and manually create spans and transactions. + +* ElasticApm - Public API entry point +* TransactionInterface +* SpanInterface +* Manual distributed tracing + +
+ +## ElasticApm +This is the entry point of the public API. +It allows to start transactions, gives you access to the current transaction, etc. + +To use the API, you invoke the static methods on the class `\Elastic\Apm\ElasticApm`. + +
+ +### `ElasticApm::beginCurrentTransaction` +Begins a new transaction and sets it as the current transaction. +Use this method to create a custom transaction. +Note that when automatic instrumentation is used +the agent begins a new transaction automatically +whenever your application receives an incoming HTTP request +so you only need to use this method to create custom transactions. + + +You must call `TransactionInterface->end` when the transaction has ended. + + +The best practice is to use a `try`-`finally` block. +For example: + +```php +use Elastic\Apm\ElasticApm; + +$transaction = ElasticApm::beginCurrentTransaction( + 'transaction_name', + 'transaction_type' +); +try { + // do your thing ... +} finally { + $transaction->end(); +} +``` + +See TransactionInterface on how to customize a transaction. + +
+ +### `ElasticApm::captureCurrentTransaction` +This is a convenience API that ensures `TransactionInterface->end` is called +when the transaction has ended. +This API: + +* Begins a new transaction +* Sets the new transaction as the current transaction +* Executes the provided `callable` as the new transaction +* Ends the new transaction +* Returns the value returned by the provided `callable` + +For example: + +```php +use Elastic\Apm\ElasticApm; +use Elastic\Apm\TransactionInterface; + +ElasticApm::captureCurrentTransaction( + 'transaction_name', + 'transaction_type', + function (TransactionInterface $transaction) { + // do your thing... + } +); +``` + +See TransactionInterface on how to customize a transaction. + +
+ +### `ElasticApm::getCurrentTransaction` +Returns the current transaction. + +```php +use Elastic\Apm\ElasticApm; + +$transaction = ElasticApm::getCurrentTransaction(); +``` + +See TransactionInterface on how to customize a transaction. + +
+ +## TransactionInterface +A transaction describes an event captured by an Elastic APM agent monitoring a service. +Transactions help combine multiple Spans into logical groups, +and they are the first Span of a service. +More information on Transactions and Spans is available +in the [APM data model](((apm-guide-ref))/data-model.html) documentation. + +See `ElasticApm::getCurrentTransaction` on how to get a reference to the current transaction. + +
+ +### `TransactionInterface->getCurrentSpan` +Returns the current span for this transaction. + +Example: + +```php +$span = $transaction->getCurrentSpan(); +``` + +
+ +### `TransactionInterface->beginCurrentSpan` +Begins a new span with the current span as the new span's parent and +sets the new span as the current span for this transaction. +If this transaction's doesn't have the current span +then the transaction itself is set as the new span's parent. + + +You must call `SpanInterface->end` when the span has ended. + + +The best practice is to use a `try`-`finally` block. +For example: + +```php +$span = $transaction->beginCurrentSpan( + 'span_name', + 'span_type', + 'span_sub-type', // optional + 'span_action' // optional +); +try { + // do your thing ... +} finally { + $span->end(); +} +``` + +
+ +### `TransactionInterface->captureCurrentSpan` +This is a convenience API that ensures `SpanInterface->end` is called +when the span has ended. +This API + +* Begins a new span with this transaction's current span as the new span's parent and + sets the new span as the current span for this transaction. + If this transaction's doesn't have a current span + then the transaction itself is set as the new span's parent. + +* Executes the provided `callable` as the new span +* Ends the new transaction +* Returns the value returned by the provided `callable` + +For example: + +```php +$parentSpan->captureCurrentSpan( + 'span_name', + 'span_type', + function (SpanInterface $childSpan) { + // do your thing... + }, + 'span_sub-type', // optional + 'span_action' // optional +); +``` + +
+ +### `TransactionInterface->beginChildSpan` +Begins a new span with this transaction as the new span's parent. + + +You must call `SpanInterface->end` when the span has ended. + + +The best practice is to use `try`-`finally` block. +For example: + +```php +$span = $transaction->beginChildSpan( + 'span_name', + 'span_type', + 'span_sub-type', // optional + 'span_action' // optional +); +try { + // do your thing ... +} finally { + $span->end(); +} +``` + +
+ +### `TransactionInterface->captureChildSpan` +This is a convenience API that ensures `SpanInterface->end` is called +when the span has ended. +This API + +* Begins a new span with this transaction as the new span's parent +* Executes the provided `callable` as the new span and +* Ends the new span +* Returns the value returned by the provided `callable` + +For example: + +```php +$transaction->captureChildSpan( + 'span_name', + 'span_type', + function (SpanInterface $span) { + // do your thing... + }, + 'span_sub-type', // optional + 'span_action' // optional +); +``` + +
+ +### `TransactionInterface->setName` +Sets the name of the transaction. +Transaction name is generic designation of a transaction in the scope of a single service (e.g., `GET /users/:id`). + +Example: + +```php +$transaction->setName('GET /users/:id'); +``` + +
+ +### `TransactionInterface->setType` +Sets the type of the transaction. +Transaction type is a keyword of specific relevance in the service's domain. +For example `request`, `backgroundjob`, etc. + +Example: + +```php +$transaction->setType('my custom transaction type'); +``` + +
+ +### `TransactionInterface->context()->setLabel` +Sets a label by a key. +Labels are a flat mapping of user-defined string keys and string, number, or boolean values. + + +The labels are indexed in Elasticsearch so that they are searchable and aggregatable. +Take special care when using user provided data, like URL parameters, +as a label key because it can lead to [Elasticsearch mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +Example: + +```php +$transaction->context()->setLabel('my label with string value', 'some text'); +$transaction->context()->setLabel('my label with int value', 123); +$transaction->context()->setLabel('my label with float value', 4.56); +``` + +
+ +### `TransactionInterface->getId` +Gets the ID of the transaction. +Transaction ID is a hex encoded 64 random bits (== 8 bytes == 16 hex digits) ID. + +If this transaction represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$transactionId = $transaction->getId(); +``` + +
+ +### `TransactionInterface->getTraceId` +Gets the trace ID of the transaction. +Trace ID is a hex encoded 128 random bits (== 16 bytes == 32 hex digits) ID of the correlated trace. + +The trace ID is consistent across all transactions and spans which belong to the same logical trace, +even for transactions and spans which happened in another service +(given this service is also monitored by Elastic APM). + +If this transaction represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$traceId = $transaction->getTraceId(); +``` + +
+ +### `TransactionInterface->getParentId` +Gets ID of the parent transaction or span. + +See `TransactionInterface->getId` and {/* `SpanInterface->getId` */}. + +The root transaction of a trace does not have a parent, so `null` is returned. + +If this transaction represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$parentId = $transaction->getParentId(); +``` + +
+ +### `TransactionInterface->ensureParentId()` +If the transaction does not have a parent-ID yet, +calling this method generates a new ID, +sets it as the parent-ID of this transaction, +and returns it as a `string`. + +This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load +with the transaction of the backend service. +If your backend service generates the HTML page dynamically, +initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services. + +An example of using this API in Laravel application can be found at https://github.com/elastic/opbeans-php/. + +Add `isElasticApmEnabled`, `elasticApmCurrentTransaction` properties to the view +([see the relevant part in opbeans-php's `AppServiceProvider.php`](https://github.com/elastic/opbeans-php/blob/22df4af76a879d8ce7237d90e953e312fb98e792/app/Providers/AppServiceProvider.php#L33)) +and add a snippet similar to the following one to the body of your HTML page, +preferably before other JS libraries +([see opbeans-php's `rendered_by_frontend.blade.php`](https://github.com/elastic/opbeans-php/blob/22df4af76a879d8ce7237d90e953e312fb98e792/resources/views/rendered_by_frontend.blade.php)) +: + +```html +@if ($isElasticApmEnabled) + +@endif +``` + +See the [JavaScript RUM agent documentation](((apm-rum-ref))) for more information. + +
+ +### `TransactionInterface->setResult` +Sets the result of the transaction. + +Transaction result is optional and can be set to `null`. +For HTTP-related transactions, the result is HTTP status code formatted like `HTTP 2xx`. + +Example: + +```php +$transaction->setResult('my custom transaction result'); +``` + +
+ +### `TransactionInterface->end` +Ends the transaction and queues it to be reported to the APM Server. + +It is illegal to call any mutating methods (for example any `set...` method is a mutating method) on a transaction instance which has already ended. + +Example: + +```php +$transaction->end(); +``` + +
+ +## SpanInterface +A span contains information about a specific code path, executed as part of a transaction. + +If for example a database query happens within a recorded transaction, +a span representing this database query may be created. +In such a case the name of the span will contain information about the query itself, +and the type will hold information about the database type. + +See `TransactionInterface->getCurrentSpan` on how to get the current span. + +
+ +### `SpanInterface->setName` +Sets the name of the span. +Span name is generic designation of a span in the scope of a transaction. + +Example: + +```php +$span->setName('SELECT FROM customer'); +``` + +
+ +### `SpanInterface->setType` +Sets the type of the span. +Span type is a keyword of specific relevance in the service's domain. +For example `db`, `external`, etc. + +Example: + +```php +$span->setType('my custom span type'); +``` + +
+ +### `SpanInterface->setSubtype` +Sets the sub-type of the span. +Span sub-type is a further sub-division of the type. +For example, `mysql`, `postgresql`, or `elasticsearch` for the type `db`, `http` for the type `external`, etc. + +Span sub-type is optional and can be set to `null`. +Span sub-type default value is `null`. + +Example: + +```php +$span->setSubtype('my custom span sub-type'); +``` + +
+ +### `SpanInterface->setAction` +Sets the action of the span. +Span action is the specific kind of event within the sub-type represented by the span. +For example `query` for type/sub-type `db`/`mysql`, `connect` for type/sub-type `db`/`cassandra`, etc. + +Span action is optional and can be set to `null`. +Span action default value is `null`. + +Example: + +```php +$span->setAction('my custom span action'); +``` + +
+ +### `SpanInterface->context()->setLabel` +Sets a label by a key. +Labels are a flat mapping of user-defined string keys and string, number, or boolean values. + + +The labels are indexed in Elasticsearch so that they are searchable and aggregatable. +Take special care when using user provided data, like URL parameters, +as a label key because it can lead to [Elasticsearch mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +Example: + +```php +$span->context()->setLabel('my label with string value', 'some text'); +$span->context()->setLabel('my label with int value', 123); +$span->context()->setLabel('my label with float value', 4.56); +``` + +
+ +### `SpanInterface->getId` +Gets the ID of the span. +Span ID is a hex encoded 64 random bits (== 8 bytes == 16 hex digits) ID. + +If this span represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$spanId = $span->getId(); +``` + +
+ +### `SpanInterface->getTraceId` +Gets the trace ID of the span. +Trace ID is a hex encoded 128 random bits (== 16 bytes == 32 hex digits) ID of the correlated trace. + +The trace ID is consistent across all transactions and spans which belong to the same logical trace, +even for transactions and spans which happened in another service +(given this service is also monitored by Elastic APM). + +If this span represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$traceId = $span->getTraceId(); +``` + +
+ +### `SpanInterface->getTransactionId` +Gets ID of the correlated transaction. +See `TransactionInterface->getId`. + +If this span represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$transactionId = $span->getTransactionId(); +``` + +
+ +### `SpanInterface->getParentId` +Gets ID of the parent transaction or span. +If this span is the root span of the correlated transaction then its parent is the correlated transaction, +otherwise, its parent is the parent span. +See `TransactionInterface->getId` and {/* `SpanInterface->getId` */}. + +If this span represents a noop, this method returns an unspecified dummy ID. + +Example: + +```php +$parentId = $span->getParentId(); +``` + +
+ +### `SpanInterface->beginChildSpan` +Begins a new span with this span as the new span's parent. + + +You must call `SpanInterface->end` when the span has ended. + + +The best practice is to use a `try`-`finally` block. +For example: + +```php +$childSpan = $parentSpan->beginChildSpan( + 'span_name', + 'span_type', + 'span_sub-type', // optional + 'span_action' // optional +); +try { + // do your thing ... +} finally { + $childSpan->end(); +} +``` + +
+ +### `SpanInterface->captureChildSpan` +This is a convenience API that ensures `SpanInterface->end` is called +when the span has ended. +This API + +* Begins a new span with this span as the new span's parent +* Executes the provided `callable` as the new span +* Ends the new span +* Returns the value returned by the provided `callable` + +For example: + +```php +$parentSpan->captureChildSpan( + 'span_name', + 'span_type', + function (SpanInterface $childSpan) { + // do your thing... + }, + 'span_sub-type', // optional + 'span_action' // optional +); +``` + +
+ +### `SpanInterface->end` +Ends the span and queues it to be reported to the APM Server. + +It is illegal to call any mutating methods (for example any `set...` method is a mutating method) on a span instance which has already ended. + +Example: + +```php +$span->end(); +``` + +
+ +## Manual distributed tracing +Elastic APM PHP agent automatically propagates distributed tracing context for supported technologies. +If your service communicates over a different, unsupported protocol, +you can manually propagate distributed tracing context from a sending service +to a receiving service using the agent's API. + +Distributed tracing data consists of multiple key-value pairs. +For example for HTTP protocol these pairs are passed as request headers. + +At the sending service you must add key-value pairs to the outgoing request. +Use `injectDistributedTracingHeaders()` API to get the distributed tracing data +from the corresponding instance of SpanInterface or {/* TransactionInterface */} + +For example assuming the outgoing request is associated with `$span` : + +```php +$span->injectDistributedTracingHeaders( + function (string $headerName, string $headerValue) use ($myRequest): void { + $myRequest->addHeader($headerName, $headerValue); + } +); +``` + +At the receiving service you must pass key-value pairs from the sending side to `ElasticApm::newTransaction` API. + +Example: + +```php +$myTransaction = ElasticApm::newTransaction('my TX name', 'my TX type') + ->distributedTracingHeaderExtractor( + function (string $headerName) use ($myRequest): ?string { + return $myRequest->hasHeader($headerName) + ? $myRequest->getHeader($headerName) + : null; + } + )->begin(); +``` diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx index 9cbdb8f040..949f005743 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx @@ -5,3 +5,586 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +
+ +## `api_key` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_API_KEY` | `elastic_apm.api_key` | + +| Default | Type | +|---|---| +| None | String | + +This string is used to ensure that only your agents can send data to your APM Server. +You must have created the API key using the APM Server [command line tool](((apm-guide-ref))/api-key.html). + +{/* `api_key` */} is an alternative to {/* `secret_token` */}. +If both {/* `secret_token` */} and {/* `api_key` */} are configured, +then {/* `api_key` */} has precedence and {/* `secret_token` */} is ignored. + + +This feature is fully supported in the APM Server versions >= 7.6. + + + +The `api_key` value is sent as plain-text in every request to the server, so you should also secure +your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. + + +
+ +## `breakdown_metrics` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_BREAKDOWN_METRICS` | `elastic_apm.breakdown_metrics` | + +| Default | Type | +|---|---| +| true | Boolean | + +If this configuration option is set to `true` the agent will collect and report +breakdown metrics (`span.self_time`) used for "Time spent by span type" chart. +Set it to `false` to disable the collection and reporting of +breakdown metrics, which can reduce the overhead of the agent. + + +This feature requires APM Server and Kibana >= 7.3. + + +
+ +## `capture_errors` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_CAPTURE_ERRORS` | `elastic_apm.capture_errors` | + +| Default | Type | +|---|---| +| true | Boolean | + +If this configuration option is set to `true` the agent will collect and report error events. +Set it to `false` to disable the collection and reporting of APM +error events, which can reduce the overhead of the agent. + +Also see PHP errors as APM error events. + +
+ +## `disable_instrumentations` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_DISABLE_INSTRUMENTATIONS` | `elastic_apm.disable_instrumentations` | + +| Default | Type | +|---|---| +| empty list | List of strings | + +A comma-separated list of wildcard expressions to match +instrumentation names which should be disabled. +When an instrumentation is disabled, no spans will be created for that instrumentation. +Each instrumentation has a name and any number of keywords. +If the instrumentation's name or any of its keywords match this configuration option +then the instrumentation is disabled. + +See Wildcard for more details on how to use wildcard expressions. + +Supported instrumentations: +| Name | Keywords | +|---|---| +| `curl` | `HTTP-client` | +| `PDO` | `DB` | +| `MySQLi` | `DB` | + +Examples: + +- `db` disables both PDO and MySQLi instrumentations +- `*HTTP*` disables curl instrumentation + +
+ +## `disable_send` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_DISABLE_SEND` | `elastic_apm.disable_send` | + +| Default | Type | +|---|---| +| false | Boolean | + +If set to `true`, the agent will work as usual, except for any task requiring +communication with the APM server. Events will be dropped and the agent won't be +able to receive central configuration, which means that any other configuration +cannot be changed in this state without restarting the service. Example uses +for this setting are: maintaining the ability to create traces and log +trace/transaction/span IDs through the log correlation feature, and getting +automatic distributed tracing via the [W3C HTTP headers](https://w3c.github.io/trace-context/). + +
+ +## `enabled` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_ENABLED` | `elastic_apm.enabled` | + +| Default | Type | +|---|---| +| true | Boolean | + +Setting to false will completely disable the agent. + +
+ +## `environment` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_ENVIRONMENT` | `elastic_apm.environment` | + +| Default | Type | +|---|---| +| None | String | + +The name of the environment this service is deployed in, e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. +It's important to be consistent when naming environments across agents. +See [environment selector](((apm-app-ref))/filters.html#environment-selector) in the Kibana UI for more information. + + +This feature is fully supported in the APM app in Kibana versions >= 7.2. +You must use the query bar to filter for a specific environment in versions prior to 7.2. + + +
+ +## `global_labels` + +| Hostname variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_GLOBAL_LABELS` | `elastic_apm.global_labels` | + +| Default | Type | +|---|---| +| empty map | string to string map | + +Labels from this configuration are added to all the entities produced by the agent. + +The format is `key=value[,key=value[,...]]`. +For example `dept=engineering,rack=number8`. + + +When setting this configuration option in `.ini` file + it is required to enclose the value in quotes (because the value contains equal sign). + For example `elastic_apm.global_labels = "dept=engineering,rack=number8"` + + +Any labels set by the application via the agent's public API +will override global labels with the same keys. + + +This option requires APM Server 7.2 or later. It will have no effect on older versions. + + +
+ +## `hostname` + +| Hostname variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_HOSTNAME` | `elastic_apm.hostname` | + +| Default | Type | +|---|---| +| the local machine's host name | String | + +This option allows for the reported host name to be configured. +If this option is not set the local machine's host name is used. + +
+ +## `log_level` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_LOG_LEVEL` | `elastic_apm.log_level` | + +| Default | Type | +|---|---| +| None | Log level | + +A fallback configuration setting to control the logging level for the agent. +Only used when a sink-specific option is not explicitly set. +See Logging for details. + +
+ +## `log_level_stderr` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_LOG_LEVEL_STDERR` | `elastic_apm.log_level_stderr` | + +| Default | Type | +|---|---| +| `CRITICAL` | Log level | + +The logging level for `stderr` logging sink. +See Logging for details. + +
+ +## `log_level_syslog` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_LOG_LEVEL_SYSLOG` | `elastic_apm.log_level_syslog` | + +| Default | Type | +|---|---| +| `INFO` | Log level | + +The logging level for `syslog` logging sink. +See Logging for details. + +
+ +## `secret_token` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SECRET_TOKEN` | `elastic_apm.secret_token` | + +| Default | Type | +|---|---| +| None | String | + +This string is used to ensure that only your agents can send data to your APM Server. +Both the agents and the APM Server have to be configured with the same secret token. + +See [the relevant APM Server's documentation](((apm-guide-ref))/secret-token.html) +on how to configure APM Server's secret token. + +Use this setting if the APM Server requires a token, like in ((ess)). + +{/* `secret_token` */} is an alternative to {/* `api_key` */}. +If both {/* `secret_token` */} and {/* `api_key` */} are configured +then {/* `api_key` */} has precedence and {/* `secret_token` */} is ignored. + + +The `secret_token` is sent as plain-text in every request to the server, so you should also secure +your communications using HTTPS. Unless you do so, your secret token could be observed by an attacker. + + +
+ +## `server_timeout` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SERVER_TIMEOUT` | `elastic_apm.server_timeout` | + +| Default | Type | +|---|---| +| `30s` | Duration | + +If a request sending events to the APM server takes longer than the configured timeout, +the request is canceled and the events are discarded. + +The value has to be provided in **duration format**. + +This option's default unit is `s` (seconds). + +If the value is `0` (or `0ms`, `0s`, etc.) the timeout for sending events to the APM Server is disabled. + +Negative values are invalid and result in the default value being used instead. + +
+ +## `server_url` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SERVER_URL` | `elastic_apm.server_url` | + +| Default | Type | +|---|---| +| `http://localhost:8200` | String | + +The URL for your APM Server. The URL must be fully qualified, including protocol (`http` or `https`) and port. + +
+ +## `service_name` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SERVICE_NAME` | `elastic_apm.service_name` | + +| Default | Type | +|---|---| +| `unknown-php-service` | String | + +This is used to keep all the errors and transactions of your service together +and is the primary filter in the Elastic APM user interface. + + +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. +In other words, a service name must only contain characters from the ASCII alphabet, +numbers, dashes, underscores, and spaces. +Characters in service name that don't match regular expression will be replaced by `_` (underscore) character. + + +
+ +## `service_node_name` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SERVICE_NODE_NAME` | `elastic_apm.service_node_name` | + +| Default | Type | +|---|---| +| None | String | + +If it's set, this name is used to distinguish between different nodes of a service. +If it's not set, data aggregations will be done based on the container ID +if the monitored application runs in a container. +Otherwise data aggregations will be done based on the reported hostname +(automatically discovered or manually configured using {/* `hostname` */}). + +
+ +## `service_version` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SERVICE_VERSION` | `elastic_apm.service_version` | + +| Default | Type | +|---|---| +| None | String | + +The version of the currently deployed service. If your deployments are not versioned, +the recommended value for this field is the commit identifier of the deployed revision, e.g., +the output of git rev-parse HEAD. + +
+ +## `span_compression_enabled` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `elastic_apm.span_compression_enabled` | + +| Default | Type | +|---|---| +| true | Boolean | + +Setting this option to true will enable span compression feature. +Span compression reduces the collection, processing, and storage overhead, +and removes clutter from the UI. +The tradeoff is that some information +such as DB statements of all the compressed spans will not be collected. + +
+ +## `span_compression_exact_match_max_duration` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `elastic_apm.span_compression_exact_match_max_duration` | + +| Default | Type | +|---|---| +| `50ms` | Duration | + +Consecutive spans that are exact match and that are under this threshold +will be compressed into a single composite span. +This option does not apply to composite spans. +This reduces the collection, processing, and storage overhead, +and removes clutter from the UI. +The tradeoff is that the DB statements of all the compressed spans will not be collected. + +Since it is **max** duration threshold setting this configuration option to 0 +effectively disables this compression strategy +because only spans with duration 0 will be considered eligible for compression with this strategy. + +This configuration option supports the duration suffixes: `ms`, `s` and `m`. +For example: `10ms`. +This option's default unit is `ms`, so `5` is interpreted as `5ms`. + +
+ +## `span_compression_same_kind_max_duration` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `elastic_apm.span_compression_same_kind_max_duration` | + +| Default | Type | +|---|---| +| `0ms` | Duration | + +Consecutive spans to the same destination that are under this threshold +will be compressed into a single composite span. +This option does not apply to composite spans. +This reduces the collection, processing, and storage overhead, +and removes clutter from the UI. +The tradeoff is that the DB statements of all the compressed spans will not be collected. + +Since it is **max** duration threshold setting this configuration option to 0 +effectively disables this compression strategy +because only spans with duration 0 will be considered eligible for compression with this strategy. + +This configuration option supports the duration suffixes: `ms`, `s` and `m`. +For example: `10ms`. +This option's default unit is `ms`, so `5` is interpreted as `5ms`. + +
+ +## `span_stack_trace_min_duration` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `elastic_apm.span_stack_trace_min_duration` | + +| Default | Type | +|---|---| +| `5ms` | Duration | + +While it might be very helpful to have stack trace attached to a span, +collecting stack traces does have some overhead. +This configuration controls the minimum span duration at which stack traces are collected. +A higher value means lower overhead as stack trace collection is skipped for quick spans. + +Set this config to: + +- any positive value (e.g. `5ms`) - to limit stack trace collection to spans with duration + equal to or greater than the given value (e.g. 5 milliseconds) +- `0` (or `0` with any duration units e.g. `0ms`) - to collect stack traces + for spans with any duration +- any negative value (e.g. `-1ms`) - to disable stack trace collection for spans completely + +This configuration option supports the duration suffixes: `ms`, `s` and `m`. +For example: `10ms`. +This option's default unit is `ms`, so `5` is interpreted as `5ms`. + +
+ +## `stack_trace_limit` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `elastic_apm.stack_trace_limit` | + +| Default | Type | +|---|---| +| `50` | Integer | + +This option controls how many frames are included in stack traces captured by the agent. + +Set this config to: + +- any positive integer - to define the maximum number of frames included in stack traces +- `0` - to disable stack trace capturing +- any negative integer - to capture all frames + +
+ +## `transaction_ignore_urls` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | `elastic_apm.transaction_ignore_urls` | + +| Default | Type | +|---|---| +| empty list | List of wildcard expressions | + +This option instructs the agent to ignore requests with certain URLs +by not to creating transactions for those requests. +It only affects automatic creation of transactions by the agent +but user can still create transactions manually by using agent's public API. + +See Wildcard section for more details on how to use wildcard expressions. + +
+ +## `transaction_max_spans` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `elastic_apm.transaction_max_spans` | + +| Default | Type | +|---|---| +| 500 | Integer | + +This limits the amount of spans that are recorded per transaction. +This is helpful in cases where a transaction creates a very high amount of spans, +for example, thousands of SQL queries. +Setting an upper limit helps prevent overloading the Agent and APM server in these edge cases. + +If the value is `0` no spans will be collected. + +Negative values are invalid and result in the default value being used instead. + +
+ +## `transaction_sample_rate` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `elastic_apm.transaction_sample_rate` | + +| Default | Type | +|---|---| +| 1.0 | Floating-point number | + +By default, the agent will sample every transaction (e.g., a request to your service). +To reduce overhead and storage requirements, set the sample rate to a value between `0.0` and `1.0`. +The agent still records the overall time and result for unsampled transactions, +but not context information, labels, or spans. + +
+ +## `verify_server_cert` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `elastic_apm.verify_server_cert` | + +| Default | Type | +|---|---| +| `true` | Boolean | + +By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM server. +The verification can be disabled by changing this setting to `false`. + +
+ +## `url_groups` + +| Environment variable name | Option name in `php.ini` | +|---|---| +| `ELASTIC_APM_URL_GROUPS` | `elastic_apm.url_groups` | + +| Default | Type | +|---|---| +| empty list | List of wildcard expressions | + +With this option, you can group several URL paths together by using wildcard expressions +like `/user/*` - this way `/user/Alice` and `/user/Bob` will be mapped to transaction name `/user/*`. + +See Wildcard section for more details on how to use wildcard expressions. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx index c528fc8e67..c939622db5 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx @@ -5,3 +5,94 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/php) + + + +
+ +
+ +## Prerequisites + +### Operating system +The agent is currently only available for the Linux operating system. + +### PHP +The agent supports PHP versions 7.2-8.2. + +### curl +The agent requires `libcurl` 7.58 or later. + +
+ +## Installation + +Install the agent using one of the [packages for supported platforms](https://github.com/elastic/apm-agent-php/releases/latest). + +
+ +### Using RPM package (RHEL/CentOS, Fedora) + +```bash +rpm -ivh .rpm +``` + +
+ +### Using DEB package (Debian, Ubuntu 18+) + +```bash +dpkg -i .deb +``` + +
+ +### Using APK package (Alpine) + +```bash +apk add --allow-untrusted .apk +``` + +
+ +### Build from source + +If you can’t find your distribution, you can install the agent by building it from the source. + + +The agent is currently only available for Linux operating system. + + +1. Download the agent source from https://github.com/elastic/apm-agent-php/. +1. Execute the following commands to build the agent and install it: + +```bash +cd src/ext +phpize +CFLAGS="-std=gnu99" ./configure --enable-elastic_apm +make clean +make +sudo make install +``` + +Enable the extension by adding the following to your `php.ini` file: + +```php +extension=elastic_apm.so +elastic_apm.bootstrap_php_part_file=/src/bootstrap_php_part.php +``` + +To work, the agent needs both the built `elastic_apm.so` +and the downloaded source files. +So if you would like to build `elastic_apm.so` on one machine and +then deploy it on a different machine, you will need to copy both +the built `elastic_apm.so` and the downloaded source files. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx index e886736737..0e102cd1a2 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx index 91b56c2259..b03c49abb1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx @@ -5,3 +5,5 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx index 905e4ae231..3801f68546 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx @@ -5,3 +5,79 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/php) + + + +
+ +If the agent doesn't support your favorite technology yet, +you can vote for it by participating in [our survey](https://docs.google.com/forms/d/e/1FAIpQLSf8c3BJVMqaeuqpq-t3_Q4NilNcdsrzK1qJ4Qo9JpJslrmYzA/viewform). +We will use the results to add support for the most requested technologies. + +
+ +## Operating systems + +The agent supports Linux operating system. + +
+ +## PHP versions + +The agent supports PHP versions 7.2-8.2. + +
+ +## Web frameworks + +Automatic instrumentation for a web framework means +a transaction is automatically created for each incoming request and it is named after the registered route. + +We support automatic instrumentation for the following web frameworks. + +| Framework | Supported versions | +|---|---| +| Framework-less PHP application (i.e., application using PHP's built in web support) | | +| Laravel | 6, 7, 8, 9, 10 | +| WordPress | 5, 6 | + +
+ +## Data access technologies + +We support automatic instrumentation for the following data access technologies. + +| Data access technology | Supported versions | Notes | +|---|---|---| +| PHP Data Objects (PDO) | any version bundled with a supported PHP version | The agent automatically creates DB spans for all your PDO queries. This includes PDO queries executed by object relational mappers (ORM) like Doctrine & Eloquent. | +| MySQLi | any version bundled with a supported PHP version | | + +
+ +## HTTP clients + +Automatic instrumentation for an HTTP client technology means +an HTTP span is automatically created for each outgoing HTTP request +and distributed tracing headers are propagated. +The spans are named after the schema ` `, for example `GET elastic.co`. + +| Framework | Supported versions | +|---|---| +| `curl` extension | | +| `Guzzle` library | | + +
+ +## Capturing PHP errors as APM error events + +The agent automatically creates APM error events for PHP errors triggered by the monitored application. +See PHP errors as APM error events for the relevant configuration settings. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx index 8b76b416e1..d9c9e35019 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx @@ -5,3 +5,30 @@ title: PHP # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/php) + + + +
+ +The Elastic APM PHP Agent measures the performance of your application and tracks errors. +It is an extension that must be installed in your PHP environment. + +{/* [float] */} +{/* */} +{/* === How does the Agent work? */} + +
+ +## Additional Components +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx index 8705e9f8d9..0507b9e05c 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx @@ -5,3 +5,549 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM Python agent has several public APIs. +Most of the public API functionality is not needed when using one of our supported frameworks, +but they allow customized usage. + +
+ +## Client API + +The public Client API consists of several methods on the `Client` class. +This API can be used to track exceptions and log messages, +as well as to mark the beginning and end of transactions. + +
+ +### Instantiation + +_Added in v1.0.0._ + +To create a `Client` instance, import it and call its constructor: + +```python +from elasticapm import Client + +client = Client({'SERVICE_NAME': 'example'}, **defaults) +``` + + * `config`: A dictionary, with key/value configuration. For the possible configuration keys, see Configuration. + * `**defaults`: default values for configuration. These can be omitted in most cases, and take the least precedence. + + +framework integrations like {/* Django and Flask */} +instantiate the client automatically. + + +
+ +#### `elasticapm.get_client()` + +_Added in v6.1.0._ + +Retrieves the `Client` singleton. This is useful for many framework integrations, +where the client is instantiated automatically. + +```python +client = elasticapm.get_client() +client.capture_message('foo') +``` + +
+ +### Errors + +
+ +#### `Client.capture_exception()` + +_Added in v1.0.0. `handled` added in v2.0.0._ + +Captures an exception object: + +```python +try: + x = int("five") +except ValueError: + client.capture_exception() +``` + + * `exc_info`: A `(type, value, traceback)` tuple as returned by [`sys.exc_info()`](https://docs.python.org/3/library/sys.html#sys.exc_info). If not provided, it will be captured automatically. + * `date`: A `datetime.datetime` object representing the occurrence time of the error. If left empty, it defaults to `datetime.datetime.utcnow()`. + * `context`: A dictionary with contextual information. This dictionary must follow the + [Context](((apm-guide-ref))/api-error.html) schema definition. + + * `custom`: A dictionary of custom data you want to attach to the event. + * `handled`: A boolean to indicate if this exception was handled or not. + +Returns the id of the error as a string. + +
+ +#### `Client.capture_message()` + +_Added in v1.0.0._ + +Captures a message with optional added contextual data. Example: + +```python +client.capture_message('Billing process succeeded.') +``` + + * `message`: The message as a string. + * `param_message`: Alternatively, a parameterized message as a dictionary. + The dictionary contains two values: `message`, and `params`. + This allows the APM Server to group messages together that share the same + parameterized message. Example: + + ```python + client.capture_message(param_message={ + 'message': 'Billing process for %s succeeded. Amount: %s', + 'params': (customer.id, order.total_amount), + }) + ``` + + * `stack`: If set to `True` (the default), a stacktrace from the call site will be captured. + * `exc_info`: A `(type, value, traceback)` tuple as returned by + [`sys.exc_info()`](https://docs.python.org/3/library/sys.html#sys.exc_info). + If not provided, it will be captured automatically, if `capture_message()` was called in an `except` block. + + * `date`: A `datetime.datetime` object representing the occurrence time of the error. + If left empty, it defaults to `datetime.datetime.utcnow()`. + + * `context`: A dictionary with contextual information. This dictionary must follow the + [Context](((apm-guide-ref))/api-error.html) schema definition. + + * `custom`: A dictionary of custom data you want to attach to the event. + +Returns the id of the message as a string. + + +Either the `message` or the `param_message` argument is required. + + +
+ +### Transactions + +
+ +#### `Client.begin_transaction()` + +_Added in v1.0.0. `trace_parent` support added in v5.6.0._ + +Begin tracking a transaction. +Should be called e.g. at the beginning of a request or when starting a background task. Example: + +```python +client.begin_transaction('processors') +``` + + * `transaction_type`: (*required*) A string describing the type of the transaction, e.g. `'request'` or `'celery'`. + * `trace_parent`: (*optional*) A `TraceParent` object. See TraceParent generation. + * `links`: (*optional*) A list of `TraceParent` objects to which this transaction is causally linked. + +
+ +#### `Client.end_transaction()` + +_Added in v1.0.0._ + +End tracking the transaction. +Should be called e.g. at the end of a request or when ending a background task. Example: + +```python +client.end_transaction('myapp.billing_process', processor.status) +``` + + * `name`: (*optional*) A string describing the name of the transaction, e.g. `process_order`. + This is typically the name of the view/controller that handles the request, or the route name. + + * `result`: (*optional*) A string describing the result of the transaction. + This is typically the HTTP status code, or e.g. `'success'` for a background task. + + +if `name` and `result` are not set in the `end_transaction()` call, +they have to be set beforehand by calling `elasticapm.set_transaction_name()` and {/* `elasticapm.set_transaction_result()` */} during the transaction. + + +
+ +### `TraceParent` + +Transactions can be started with a `TraceParent` object. This creates a +transaction that is a child of the `TraceParent`, which is essential for +distributed tracing. + +
+ +#### `elasticapm.trace_parent_from_string()` + +_Added in v5.6.0._ + +Create a `TraceParent` object from the string representation generated by +`TraceParent.to_string()`: + +```python +parent = elasticapm.trace_parent_from_string('00-03d67dcdd62b7c0f7a675424347eee3a-5f0e87be26015733-01') +client.begin_transaction('processors', trace_parent=parent) +``` + + * `traceparent_string`: (*required*) A string representation of a `TraceParent` object. + +
+ +#### `elasticapm.trace_parent_from_headers()` + +_Added in v5.6.0._ + +Create a `TraceParent` object from HTTP headers (usually generated by another +Elastic APM agent): + +```python +parent = elasticapm.trace_parent_from_headers(headers_dict) +client.begin_transaction('processors', trace_parent=parent) +``` + + * `headers`: (*required*) HTTP headers formed as a dictionary. + +
+ +#### `elasticapm.get_trace_parent_header()` + +_Added in v5.10.0._ + +Return the string representation of the current transaction `TraceParent` object: + +```python +elasticapm.get_trace_parent_header() +``` + +
+ +## Other APIs + +
+ +### `elasticapm.instrument()` + +_Added in v1.0.0._ + +Instruments libraries automatically. +This includes a wide range of standard library and 3rd party modules. +A list of instrumented modules can be found in `elasticapm.instrumentation.register`. +This function should be called as early as possibly in the startup of your application. +For supported frameworks, this is called automatically. Example: + +```python +import elasticapm + +elasticapm.instrument() +``` + +
+ +### `elasticapm.set_transaction_name()` + +_Added in v1.0.0._ + +Set the name of the current transaction. +For supported frameworks, the transaction name is determined automatically, +and can be overridden using this function. Example: + +```python +import elasticapm + +elasticapm.set_transaction_name('myapp.billing_process') +``` + + * `name`: (*required*) A string describing name of the transaction + * `override`: if `True` (the default), overrides any previously set transaction name. + If `False`, only sets the name if the transaction name hasn't already been set. + +
+ +### `elasticapm.set_transaction_result()` + +_Added in v2.2.0._ + +Set the result of the current transaction. +For supported frameworks, the transaction result is determined automatically, +and can be overridden using this function. Example: + +```python +import elasticapm + +elasticapm.set_transaction_result('SUCCESS') +``` + + * `result`: (*required*) A string describing the result of the transaction, e.g. `HTTP 2xx` or `SUCCESS` + * `override`: if `True` (the default), overrides any previously set result. + If `False`, only sets the result if the result hasn't already been set. + +
+ +### `elasticapm.set_transaction_outcome()` + +_Added in v5.9.0._ + +Sets the outcome of the transaction. The value can either be `"success"`, `"failure"` or `"unknown"`. +This should only be called at the end of a transaction after the outcome is determined. + +The `outcome` is used for error rate calculations. +`success` denotes that a transaction has concluded successful, while `failure` indicates that the transaction failed +to finish successfully. +If the `outcome` is set to `unknown`, the transaction will not be included in error rate calculations. + +For supported web frameworks, the transaction outcome is set automatically if it has not been set yet, based on the +HTTP status code. +A status code below `500` is considered a `success`, while any value of `500` or higher is counted as a `failure`. + +If your transaction results in an HTTP response, you can alternatively provide the HTTP status code. + + +While the `outcome` and `result` field look very similar, they serve different purposes. + Other than the `result` field, which canhold an arbitrary string value, + `outcome` is limited to three different values, + `"success"`, `"failure"` and `"unknown"`. + This allows the APM app to perform error rate calculations on these values. + + +Example: + +```python +import elasticapm + +elasticapm.set_transaction_outcome("success") + +# Using an HTTP status code +elasticapm.set_transaction_outcome(http_status_code=200) + +# Using predefined constants: + +from elasticapm.conf.constants import OUTCOME + +elasticapm.set_transaction_outcome(OUTCOME.SUCCESS) +elasticapm.set_transaction_outcome(OUTCOME.FAILURE) +elasticapm.set_transaction_outcome(OUTCOME.UNKNOWN) +``` + + * `outcome`: One of `"success"`, `"failure"` or `"unknown"`. Can be omitted if `http_status_code` is provided. + * `http_status_code`: if the transaction represents an HTTP response, its status code can be provided to determine the `outcome` automatically. + * `override`: if `True` (the default), any previously set `outcome` will be overriden. + If `False`, the outcome will only be set if it was not set before. + +
+ +### `elasticapm.get_transaction_id()` + +_Added in v5.2.0._ + +Get the id of the current transaction. Example: + +```python +import elasticapm + +transaction_id = elasticapm.get_transaction_id() +``` + +
+ +### `elasticapm.get_trace_id()` + +_Added in v5.2.0._ + +Get the `trace_id` of the current transaction's trace. Example: + +```python +import elasticapm + +trace_id = elasticapm.get_trace_id() +``` + +
+ +### `elasticapm.get_span_id()` + +_Added in v5.2.0._ + +Get the id of the current span. Example: + +```python +import elasticapm + +span_id = elasticapm.get_span_id() +``` + +
+ +### `elasticapm.set_custom_context()` + +_Added in v2.0.0._ + +Attach custom contextual data to the current transaction and errors. +Supported frameworks will automatically attach information about the HTTP request and the logged in user. +You can attach further data using this function. + + +Before using custom context, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +Example: + +```python +import elasticapm + +elasticapm.set_custom_context({'billing_amount': product.price * item_count}) +``` + + * `data`: (*required*) A dictionary with the data to be attached. This should be a flat key/value `dict` object. + + +`.`, `*`, and `"` are invalid characters for key names and will be replaced with `_`. + + +Errors that happen after this call will also have the custom context attached to them. +You can call this function multiple times, new context data will be merged with existing data, +following the `update()` semantics of Python dictionaries. + +
+ +### `elasticapm.set_user_context()` + +_Added in v2.0.0._ + +Attach information about the currently logged in user to the current transaction and errors. +Example: + +```python +import elasticapm + +elasticapm.set_user_context(username=user.username, email=user.email, user_id=user.id) +``` + + * `username`: The username of the logged in user + * `email`: The email of the logged in user + * `user_id`: The unique identifier of the logged in user, e.g. the primary key value + +Errors that happen after this call will also have the user context attached to them. +You can call this function multiple times, new user data will be merged with existing data, +following the `update()` semantics of Python dictionaries. + +
+ +### `elasticapm.capture_span` + +_Added in v4.1.0._ + +Capture a custom span. +This can be used either as a function decorator or as a context manager (in a `with` statement). +When used as a decorator, the name of the span will be set to the name of the function. +When used as a context manager, a name has to be provided. + +```python +import elasticapm + +@elasticapm.capture_span() +def coffee_maker(strength): + fetch_water() + + with elasticapm.capture_span('near-to-machine', labels={"type": "arabica"}): + insert_filter() + for i in range(strength): + pour_coffee() + + start_drip() + + fresh_pots() +``` + + * `name`: The name of the span. Defaults to the function name if used as a decorator. + * `span_type`: (*optional*) The type of the span, usually in a dot-separated hierarchy of `type`, `subtype`, and `action`, e.g. `db.mysql.query`. Alternatively, type, subtype and action can be provided as three separate arguments, see `span_subtype` and `span_action`. + * `skip_frames`: (*optional*) The number of stack frames to skip when collecting stack traces. Defaults to `0`. + * `leaf`: (*optional*) if `True`, all spans nested bellow this span will be ignored. Defaults to `False`. + * `labels`: (*optional*) a dictionary of labels. Keys must be strings, values can be strings, booleans, or numerical (`int`, `float`, `decimal.Decimal`). Defaults to `None`. + * `span_subtype`: (*optional*) subtype of the span, e.g. name of the database. Defaults to `None`. + * `span_action`: (*optional*) action of the span, e.g. `query`. Defaults to `None`. + * `links`: (*optional*) A list of `TraceParent` objects to which this span is causally linked. + +
+ +### `elasticapm.async_capture_span` + +_Added in v5.4.0._ + +Capture a custom async-aware span. +This can be used either as a function decorator or as a context manager (in an `async with` statement). +When used as a decorator, the name of the span will be set to the name of the function. +When used as a context manager, a name has to be provided. + +```python +import elasticapm + +@elasticapm.async_capture_span() +async def coffee_maker(strength): + await fetch_water() + + async with elasticapm.async_capture_span('near-to-machine', labels={"type": "arabica"}): + await insert_filter() + async for i in range(strength): + await pour_coffee() + + start_drip() + + fresh_pots() +``` + + * `name`: The name of the span. Defaults to the function name if used as a decorator. + * `span_type`: (*optional*) The type of the span, usually in a dot-separated hierarchy of `type`, `subtype`, and `action`, e.g. `db.mysql.query`. Alternatively, type, subtype and action can be provided as three separate arguments, see `span_subtype` and `span_action`. + * `skip_frames`: (*optional*) The number of stack frames to skip when collecting stack traces. Defaults to `0`. + * `leaf`: (*optional*) if `True`, all spans nested bellow this span will be ignored. Defaults to `False`. + * `labels`: (*optional*) a dictionary of labels. Keys must be strings, values can be strings, booleans, or numerical (`int`, `float`, `decimal.Decimal`). Defaults to `None`. + * `span_subtype`: (*optional*) subtype of the span, e.g. name of the database. Defaults to `None`. + * `span_action`: (*optional*) action of the span, e.g. `query`. Defaults to `None`. + * `links`: (*optional*) A list of `TraceParent` objects to which this span is causally linked. + + +`asyncio` is only supported for Python 3.7+. + + +
+ +### `elasticapm.label()` + +_Added in v5.0.0._ + +Attach labels to the the current transaction and errors. + + +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +Example: + +```python +import elasticapm + +elasticapm.label(ecommerce=True, dollar_value=47.12) +``` + +Errors that happen after this call will also have the labels attached to them. +You can call this function multiple times, new labels will be merged with existing labels, +following the `update()` semantics of Python dictionaries. + +Keys must be strings, values can be strings, booleans, or numerical (`int`, `float`, `decimal.Decimal`) +`.`, `*`, and `"` are invalid characters for label names and will be replaced with `_`. + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx index 668569ebb2..2348c0bfe0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx @@ -5,3 +5,1271 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +To adapt the Elastic APM agent to your needs, configure it using environment variables or framework-specific +configuration. + +You can either configure the agent by setting environment variables: + +```bash +ELASTIC_APM_SERVICE_NAME=foo python manage.py runserver +``` + +or with inline configuration: + +```python +apm_client = Client(service_name="foo") +``` + +or by using framework specific configuration e.g. in your Django `settings.py` file: + +```python +ELASTIC_APM = { + "SERVICE_NAME": "foo", +} +``` + +The precedence is as follows: + + * Central configuration + (supported options are marked with Dynamic ) + + * Environment variables + * Inline configuration + * Framework-specific configuration + * Default value + +
+ +## Dynamic configuration + +Configuration options marked with the Dynamic badge can be changed at runtime +when set from a supported source. + +The Python Agent supports [Central configuration](((apm-app-ref))/agent-configuration.html), +which allows you to fine-tune certain configurations from in the APM app. +This feature is enabled in the Agent by default with `central_config`. + +
+ +## Django + +To configure Django, add an `ELASTIC_APM` dictionary to your `settings.py`: + +```python +ELASTIC_APM = { + 'SERVICE_NAME': 'my-app', + 'SECRET_TOKEN': 'changeme', +} +``` + +
+ +## Flask + +To configure Flask, add an `ELASTIC_APM` dictionary to your `app.config`: + +```python +app.config['ELASTIC_APM'] = { + 'SERVICE_NAME': 'my-app', + 'SECRET_TOKEN': 'changeme', +} + +apm = ElasticAPM(app) +``` + +
+ +## Core options + +
+ +### `service_name` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVICE_NAME` | `SERVICE_NAME` | `unknown-python-service` | `my-app` | + +The name of your service. +This is used to keep all the errors and transactions of your service together +and is the primary filter in the Elastic APM user interface. + +While a default is provided, it is essential that you override this default +with something more descriptive and unique across your infrastructure. + + +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. +In other words, the service name must only contain characters from the ASCII +alphabet, numbers, dashes, underscores, and spaces. It cannot be an empty string +or whitespace-only. + + +
+ +### `server_url` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SERVER_URL` | `SERVER_URL` | `'http://127.0.0.1:8200'` | + +The URL for your APM Server. +The URL must be fully qualified, including protocol (`http` or `https`) and port. +Note: Do not set this if you are using APM in an AWS lambda function. APM Agents are designed to proxy their calls to the APM Server through the lambda extension. Instead, set `ELASTIC_APM_LAMBDA_APM_SERVER`. For more info, see {/* AWS Lambda */}. + +
+ +## `enabled` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_ENABLED` | `ENABLED` | `true` | + +Enable or disable the agent. +When set to false, the agent will not collect any data or start any background threads. + +
+ +## `recording` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_RECORDING` | `RECORDING` | `true` | + +Enable or disable recording of events. +If set to false, then the Python agent does not send any events to the Elastic APM server, +and instrumentation overhead is minimized. The agent will continue to poll the server for configuration changes. + +
+ +## Logging Options + +
+ +### `log_level` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_LOG_LEVEL` | `LOG_LEVEL` | | + +The `logging.logLevel` at which the `elasticapm` logger will log. The available +options are: + +* `"off"` (sets `logging.logLevel` to 1000) +* `"critical"` +* `"error"` +* `"warning"` +* `"info"` +* `"debug"` +* `"trace"` (sets `logging.log_level` to 5) + +Options are case-insensitive + +Note that this option doesn't do anything with logging handlers. In order +for any logs to be visible, you must either configure a handler +([`logging.basicConfig`](https://docs.python.org/3/library/logging.html#logging.basicConfig) +will do this for you) or set `log_file`. This will also override +any log level your app has set for the `elasticapm` logger. + +
+ +### `log_file` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_LOG_FILE` | `LOG_FILE` | `""` | `"/var/log/elasticapm/log.txt"` | + +This enables the agent to log to a file. This is disabled by default. The agent will log +at the `logging.logLevel` configured with `log_level`. Use +`log_file_size` to configure the maximum size of the log file. This log +file will automatically rotate. + +Note that setting `log_level` is required for this setting to do +anything. + +If [`ecs_logging`](https://github.com/elastic/ecs-logging-python) is installed, +the logs will automatically be formatted as ecs-compatible json. + +
+ +### `log_file_size` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_LOG_FILE_SIZE` | `LOG_FILE_SIZE` | `"50mb"` | `"100mb"` | + +The size of the log file if `log_file` is set. + +The agent always keeps one backup file when rotating, so the maximum space that +the log files will consume is twice the value of this setting. + +
+ +### `log_ecs_reformatting` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_LOG_ECS_REFORMATTING` | `LOG_ECS_REFORMATTING` | `"off"` | + + +Valid options: + +* `"off"` +* `"override"` + +If [`ecs_logging`](https://github.com/elastic/ecs-logging-python) is installed, +setting this to `"override"` will cause the agent to automatically attempt to enable +ecs-formatted logging. + +For base `logging` from the standard library, the agent will get the root +logger, find any attached handlers, and for each, set the formatter to +`ecs_logging.StdlibFormatter()`. + +If `structlog` is installed, the agent will override any configured processors +with `ecs_logging.StructlogFormatter()`. + +Note that this is a very blunt instrument that could have unintended side effects. +If problems arise, please apply these formatters manually and leave this setting +as `"off"`. See the +[`ecs_logging` docs](https://www.elastic.co/guide/en/ecs-logging/python/current/installation.html) +for more information about using these formatters. + +Also note that this setting does not facilitate shipping logs to Elasticsearch. +We recommend [Filebeat](https://www.elastic.co/beats/filebeat) for that purpose. + +
+ +## Other options + +
+ +### `transport_class` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_TRANSPORT_CLASS` | `TRANSPORT_CLASS` | `elasticapm.transport.http.Transport` | + +The transport class to use when sending events to the APM Server. + +
+ +### `service_node_name` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVICE_NODE_NAME` | `SERVICE_NODE_NAME` | `None` | `"redis1"` | + +The name of the given service node. This is optional and if omitted, the APM +Server will fall back on `system.container.id` if available, and +`host.name` if necessary. + +This option allows you to set the node name manually to ensure it is unique and meaningful. + +
+ +### `environment` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_ENVIRONMENT` | `ENVIRONMENT` | `None` | `"production"` | + +The name of the environment this service is deployed in, +e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. +It's important to be consistent when naming environments across agents. +See [environment selector](((apm-app-ref))/filters.html#environment-selector) in the APM app for more information. + + +This feature is fully supported in the APM app in Kibana versions >= 7.2. +You must use the query bar to filter for a specific environment in versions prior to 7.2. + + +
+ +### `cloud_provider` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_CLOUD_PROVIDER` | `CLOUD_PROVIDER` | `"auto"` | `"aws"` | + +This config value allows you to specify which cloud provider should be assumed +for metadata collection. By default, the agent will attempt to detect the cloud +provider or, if that fails, will use trial and error to collect the metadata. + +Valid options are `"auto"`, `"aws"`, `"gcp"`, and `"azure"`. If this config value is set +to `"none"`, then no cloud metadata will be collected. + +
+ +### `secret_token` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SECRET_TOKEN` | `SECRET_TOKEN` | `None` | A random string | + +This string is used to ensure that only your agents can send data to your APM Server. +Both the agents and the APM Server have to be configured with the same secret token. +An example to generate a secure secret token is: + +```bash +python -c "import secrets; print(secrets.token_urlsafe(32))" +``` + + +Secret tokens only provide any security if your APM Server uses TLS. + + +
+ +### `api_key` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_API_KEY` | `API_KEY` | `None` | A base64-encoded string | + + +{/* TODO: add link to APM Server API Key docs once the docs are released */} + +This base64-encoded string is used to ensure that only your agents can send data to your APM Server. +The API key must be created using the [APM server command-line tool](((apm-guide-ref))/api-key.html). + + +API keys only provide any real security if your APM Server uses TLS. + + +
+ +### `service_version` +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVICE_VERSION` | `SERVICE_VERSION` | `None` | A string indicating the version of the deployed service | + +A version string for the currently deployed version of the service. +If youre deploys are not versioned, the recommended value for this field is the commit identifier of the deployed revision, e.g. the output of `git rev-parse HEAD`. + +
+ +### `framework_name` +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_FRAMEWORK_NAME` | `FRAMEWORK_NAME` | Depending on framework | + +The name of the used framework. +For Django and Flask, this defaults to `django` and `flask` respectively, +otherwise, the default is `None`. + +
+ +### `framework_version` +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_FRAMEWORK_VERSION` | `FRAMEWORK_VERSION` | Depending on framework | + +The version number of the used framework. +For Django and Flask, this defaults to the used version of the framework, +otherwise, the default is `None`. + +
+ +### `filter_exception_types` +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_FILTER_EXCEPTION_TYPES` | `FILTER_EXCEPTION_TYPES` | `[]` | `['OperationalError', 'mymodule.SomeoneElsesProblemError']` | + +A list of exception types to be filtered. +Exceptions of these types will not be sent to the APM Server. + +
+ +### `transaction_ignore_urls` + +Dynamic + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | `TRANSACTION_IGNORE_URLS` | `[]` | `['/api/ping', '/static/*']` | + +A list of URLs for which the agent should not capture any transaction data. + +Optionally, `*` can be used to match multiple URLs at once. + +
+ +### `transactions_ignore_patterns` +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_TRANSACTIONS_IGNORE_PATTERNS` | `TRANSACTIONS_IGNORE_PATTERNS` | `[]` | `['^OPTIONS ', 'myviews.Healthcheck']` | + +A list of regular expressions. +Transactions with a name that matches any of the configured patterns will be ignored and not sent to the APM Server. + + +as the the name of the transaction can only be determined at the end of the transaction, +the agent might still cause overhead for transactions ignored through this setting. +If agent overhead is a concern, we recommend `transaction_ignore_urls` instead. + + +
+ +### `server_timeout` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SERVER_TIMEOUT` | `SERVER_TIMEOUT` | `"5s"` | + +A timeout for requests to the APM Server. +The setting has to be provided in **duration format**. +If a request to the APM Server takes longer than the configured timeout, +the request is cancelled and the event (exception or transaction) is discarded. +Set to `None` to disable timeouts. + + +If timeouts are disabled or set to a high value, +your app could experience memory issues if the APM Server times out. + + +
+ +### `hostname` + +| Environment | Django/Flask | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_HOSTNAME` | `HOSTNAME` | `socket.gethostname()` | `app-server01.example.com` | + +The host name to use when sending error and transaction data to the APM Server. + +
+ +### `auto_log_stacks` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_AUTO_LOG_STACKS` | `AUTO_LOG_STACKS` | `True` | +| set to `"true"` / `"false"` | | | + +If set to `True` (the default), the agent will add a stack trace to each log event, +indicating where the log message has been issued. + +This setting can be overridden on an individual basis by setting the `extra`-key `stack`: + +```python +logger.info('something happened', extra={'stack': False}) +``` + +
+ +### `collect_local_variables` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_COLLECT_LOCAL_VARIABLES` | `COLLECT_LOCAL_VARIABLES` | `errors` | + +Possible values: `errors`, `transactions`, `all`, `off` + +The Elastic APM Python agent can collect local variables for stack frames. +By default, this is only done for errors. + + +Collecting local variables has a non-trivial overhead. +Collecting local variables for transactions in production environments +can have adverse effects for the performance of your service. + + +
+ +### `local_var_max_length` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_LOCAL_VAR_MAX_LENGTH` | `LOCAL_VAR_MAX_LENGTH` | `200` | + +When collecting local variables, they will be converted to strings. +This setting allows you to limit the length of the resulting string. + +
+ +### `local_var_list_max_length` + +| | | | +|---|---|---| +| Environment | Django/Flask | Default | +| `ELASTIC_APM_LOCAL_VAR_LIST_MAX_LENGTH` | `LOCAL_VAR_LIST_MAX_LENGTH` | `10` | + +This setting allows you to limit the length of lists in local variables. + +
+ +### `local_var_dict_max_length` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_LOCAL_VAR_DICT_MAX_LENGTH` | `LOCAL_VAR_DICT_MAX_LENGTH` | `10` | + +This setting allows you to limit the length of dicts in local variables. + +
+ +### `source_lines_error_app_frames` + +
+ +### `source_lines_error_library_frames` + +
+ +### `source_lines_span_app_frames` + +
+ +### `source_lines_span_library_frames` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES` | `SOURCE_LINES_ERROR_APP_FRAMES` | `5` | +| `ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `5` | +| `ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES` | `SOURCE_LINES_SPAN_APP_FRAMES` | `0` | +| `ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES` | `SOURCE_LINES_SPAN_LIBRARY_FRAMES` | `0` | + +By default, the APM agent collects source code snippets for errors. +This setting allows you to modify the number of lines of source code that are being collected. + +We differ between errors and spans, as well as library frames and app frames. + + +Especially for spans, collecting source code can have a large impact on storage use in your Elasticsearch cluster. + + +
+ +### `capture_body` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_CAPTURE_BODY` | `CAPTURE_BODY` | `off` | + +For transactions that are HTTP requests, +the Python agent can optionally capture the request body (e.g. `POST` variables). + +Possible values: `errors`, `transactions`, `all`, `off`. + +If the request has a body and this setting is disabled, the body will be shown as `[REDACTED]`. + +For requests with a content type of `multipart/form-data`, +any uploaded files will be referenced in a special `_files` key. +It contains the name of the field and the name of the uploaded file, if provided. + + +Request bodies often contain sensitive values like passwords and credit card numbers. +If your service handles data like this, we advise to only enable this feature with care. + + +
+ +### `capture_headers` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_CAPTURE_HEADERS` | `CAPTURE_HEADERS` | `true` | + +For transactions and errors that happen due to HTTP requests, +the Python agent can optionally capture the request and response headers. + +Possible values: `true`, `false` + + +Request headers often contain sensitive values like session IDs and cookies. +See {/* sanitizing data */} for more information on how to filter out sensitive data. + + +
+ +### `transaction_max_spans` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `TRANSACTION_MAX_SPANS` | `500` | + +This limits the amount of spans that are recorded per transaction. +This is helpful in cases where a transaction creates a very high amount of spans (e.g. thousands of SQL queries). +Setting an upper limit will prevent edge cases from overloading the agent and the APM Server. + +
+ +### `stack_trace_limit` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `STACK_TRACE_LIMIT` | `50` | + +This limits the number of frames captured for each stack trace. + +Setting the limit to `0` will disable stack trace collection, +while any positive integer value will be used as the maximum number of frames to collect. +To disable the limit and always capture all frames, set the value to `-1`. + +
+ +### `span_stack_trace_min_duration` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `SPAN_STACK_TRACE_MIN_DURATION` | `"5ms"` | + +By default, the APM agent collects a stack trace with every recorded span +that has a duration equal to or longer than this configured threshold. While +stack traces are very helpful to find the exact place in your code from which a +span originates, collecting this stack trace does have some overhead. Tune this +threshold to ensure that you only collect stack traces for spans that +could be problematic. + +To collect traces for all spans, regardless of their length, set the value to `0`. + +To disable stack trace collection for spans completely, set the value to `-1`. + +Except for the special values `-1` and `0`, +this setting should be provided in **duration format**. + +
+ +### `span_frames_min_duration` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `SPAN_FRAMES_MIN_DURATION` | `"5ms"` | + + +This config value is being deprecated. Use +`span_stack_trace_min_duration` instead. + + +
+ +### `span_compression_enabled` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `SPAN_COMPRESSION_ENABLED` | `True` | + +Enable/disable span compression. + +If enabled, the agent will compress very short, repeated spans into a single span, +which is beneficial for storage and processing requirements. +Some information is lost in this process, e.g. exact durations of each compressed span. + +
+ +### `span_compression_exact_match_max_duration` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `"50ms"` | + +Consecutive spans that are exact match and that are under this threshold will be compressed into a single composite span. +This reduces the collection, processing, and storage overhead, and removes clutter from the UI. +The tradeoff is that the DB statements of all the compressed spans will not be collected. + +Two spans are considered exact matches if the following attributes are identical: + * span name + * span type + * span subtype + * destination resource (e.g. the Database name) + +
+ +### `span_compression_same_kind_max_duration` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `"0ms"` (disabled) | + +Consecutive spans to the same destination that are under this threshold will be compressed into a single composite span. +This reduces the collection, processing, and storage overhead, and removes clutter from the UI. +The tradeoff is that metadata such as database statements of all the compressed spans will not be collected. + +Two spans are considered to be of the same kind if the following attributes are identical: + * span type + * span subtype + * destination resource (e.g. the Database name) + +
+ +### `exit_span_min_duration` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` | `EXIT_SPAN_MIN_DURATION` | `"0ms"` | + +Exit spans are spans that represent a call to an external service, like a database. +If such calls are very short, they are usually not relevant and can be ignored. + +This feature is disabled by default. + + +if a span propagates distributed tracing IDs, it will not be ignored, even if it is shorter than the configured threshold. +This is to ensure that no broken traces are recorded. + + +
+ +### `api_request_size` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_API_REQUEST_SIZE` | `API_REQUEST_SIZE` | `"768kb"` | + +The maximum queue length of the request buffer before sending the request to the APM Server. +A lower value will increase the load on your APM Server, +while a higher value can increase the memory pressure of your app. +A higher value also impacts the time until data is indexed and searchable in Elasticsearch. + +This setting is useful to limit memory consumption if you experience a sudden spike of traffic. +It has to be provided in **size format**. + + +Due to internal buffering of gzip, the actual request size can be a few kilobytes larger than the given limit. +By default, the APM Server limits request payload size to `1 MByte`. + + +
+ +### `api_request_time` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_API_REQUEST_TIME` | `API_REQUEST_TIME` | `"10s"` | + +The maximum queue time of the request buffer before sending the request to the APM Server. +A lower value will increase the load on your APM Server, +while a higher value can increase the memory pressure of your app. +A higher value also impacts the time until data is indexed and searchable in Elasticsearch. + +This setting is useful to limit memory consumption if you experience a sudden spike of traffic. +It has to be provided in **duration format**. + + +The actual time will vary between 90-110% of the given value, +to avoid stampedes of instances that start at the same time. + + +
+ +### `processors` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_PROCESSORS` | `PROCESSORS` | `['elasticapm.processors.sanitize_stacktrace_locals', 'elasticapm.processors.sanitize_http_request_cookies', 'elasticapm.processors.sanitize_http_headers', 'elasticapm.processors.sanitize_http_wsgi_env', 'elasticapm.processors.sanitize_http_request_body']` | + +A list of processors to process transactions and errors. +For more information, see {/* Sanitizing Data */}. + + +We recommend always including the default set of validators if you customize this setting. + + +
+ +### `sanitize_field_names` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `SANITIZE_FIELD_NAMES` | `["password", "passwd", "pwd", "secret", "*key", "*token*", "*session*", "*credit*", "*card*", "*auth*", "*principal*", "set-cookie"]` | + +A list of glob-matched field names to match and mask when using processors. +For more information, see {/* Sanitizing Data */}. + + +We recommend always including the default set of field name matches +if you customize this setting. + + +
+ +### `transaction_sample_rate` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `TRANSACTION_SAMPLE_RATE` | `1.0` | + +By default, the agent samples every transaction (e.g. request to your service). +To reduce overhead and storage requirements, set the sample rate to a value between `0.0` and `1.0`. +We still record overall time and the result for unsampled transactions, but no context information, labels, or spans. + + +This setting will be automatically rounded to 4 decimals of precision. + + +
+ +### `include_paths` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_INCLUDE_PATHS` | `INCLUDE_PATHS` | `[]` | +| multiple values separated by commas, without spaces | | | + +A set of paths, optionally using shell globs +(see [`fnmatch`](https://docs.python.org/3/library/fnmatch.html) for a description of the syntax). +These are matched against the absolute filename of every frame, and if a pattern matches, the frame is considered +to be an "in-app frame". + +`include_paths` **takes precedence** over `exclude_paths`. + +
+ +### `exclude_paths` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_EXCLUDE_PATHS` | `EXCLUDE_PATHS` | Varies on Python version and implementation | +| multiple values separated by commas, without spaces | | | + +A set of paths, optionally using shell globs +(see [`fnmatch`](https://docs.python.org/3/library/fnmatch.html) for a description of the syntax). +These are matched against the absolute filename of every frame, and if a pattern matches, the frame is considered +to be a "library frame". + +`include_paths` **takes precedence** over `exclude_paths`. + +The default value varies based on your Python version and implementation, e.g.: + + * PyPy3: `['\*/lib-python/3/*', '\*/site-packages/*']` + * CPython 2.7: `['\*/lib/python2.7/*', '\*/lib64/python2.7/*']` + +
+ +### `debug` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_DEBUG` | `DEBUG` | `False` | + +If your app is in debug mode (e.g. in Django with `settings.DEBUG = True` or in Flask with `app.debug = True`), +the agent won't send any data to the APM Server. You can override it by changing this setting to `True`. + +
+ +### `disable_send` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_DISABLE_SEND` | `DISABLE_SEND` | `False` | + +If set to `True`, the agent won't send any events to the APM Server, independent of any debug state. + +
+ +### `instrument` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_INSTRUMENT` | `INSTRUMENT` | `True` | + +If set to `False`, the agent won't instrument any code. +This disables most of the tracing functionality, but can be useful to debug possible instrumentation issues. + +
+ +### `verify_server_cert` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `VERIFY_SERVER_CERT` | `True` | + +By default, the agent verifies the SSL certificate if an HTTPS connection to the APM Server is used. +Verification can be disabled by changing this setting to `False`. +This setting is ignored when `server_cert` is set. + +
+ +### `server_cert` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SERVER_CERT` | `SERVER_CERT` | `None` | + +If you have configured your APM Server with a self-signed TLS certificate, or you +just wish to pin the server certificate, you can specify the path to the PEM-encoded +certificate via the `ELASTIC_APM_SERVER_CERT` configuration. + + +If this option is set, the agent only verifies that the certificate provided by the APM Server is +identical to the one configured here. Validity of the certificate is not checked. + + +
+ +### `server_ca_cert_file` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_SERVER_CA_CERT_FILE` | `SERVER_CA_CERT_FILE` | `None` | + +By default, the agent will validate the TLS/SSL certificate of the APM Server using the well-known CAs curated by Mozilla, +and provided by the [`certifi`](https://pypi.org/project/certifi/) package. + +You can set this option to the path of a file containing a CA certificate that will be used instead. + +Specifying this option is required when using self-signed certificates, unless server certificate validation is disabled. + +
+ +### `use_certifi` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_USE_CERTIFI` | `USE_CERTIFI` | `True` | + +By default, the Python Agent uses the [`certifi`](https://pypi.org/project/certifi/) certificate store. +To use Python's default mechanism for finding certificates, set this option to `False`. + +
+ +### `metrics_interval` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_METRICS_INTERVAL` | `METRICS_INTERVAL` | `30s` | + +The interval in which the agent collects metrics. A shorter interval increases the granularity of metrics, +but also increases the overhead of the agent, as well as storage requirements. + +It has to be provided in **duration format**. + +
+ +### `disable_metrics` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_DISABLE_METRICS` | `DISABLE_METRICS` | `None` | + +A comma-separated list of dotted metrics names that should not be sent to the APM Server. +You can use `*` to match multiple metrics; for example, to disable all CPU-related metrics, +as well as the "total system memory" metric, set `disable_metrics` to: + +.... +"*.cpu.*,system.memory.total" +.... + + +This setting only disables the **sending** of the given metrics, not collection. + + +
+ +### `breakdown_metrics` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_BREAKDOWN_METRICS` | `BREAKDOWN_METRICS` | `True` | + +Enable or disable the tracking and collection of breakdown metrics. +Setting this to `False` disables the tracking of breakdown metrics, which can reduce the overhead of the agent. + + +This feature requires APM Server and Kibana >= 7.3. + + +
+ +### `prometheus_metrics` (Beta) + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_PROMETHEUS_METRICS` | `PROMETHEUS_METRICS` | `False` | + +Enable/disable the tracking and collection of metrics from `prometheus_client`. + +See {/* Prometheus metric set (beta) */} for more information. + + +This feature is currently in beta status. + + +
+ +### `prometheus_metrics_prefix` (Beta) + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_PROMETHEUS_METRICS_PREFIX` | `PROMETHEUS_METRICS_PREFIX` | `prometheus.metrics.` | + +A prefix to prepend to Prometheus metrics names. + +See {/* Prometheus metric set (beta) */} for more information. + + +This feature is currently in beta status. + + +
+ +### `metrics_sets` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_METRICS_SETS` | `METRICS_SETS` | ["elasticapm.metrics.sets.cpu.CPUMetricSet"] | + +List of import paths for the MetricSets that should be used to collect metrics. + +See {/* Custom Metrics */} for more information. + +
+ +### `central_config` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_CENTRAL_CONFIG` | `CENTRAL_CONFIG` | `True` | + +When enabled, the agent will make periodic requests to the APM Server to fetch updated configuration. + +See Dynamic configuration for more information. + + +This feature requires APM Server and Kibana >= 7.3. + + +
+ +### `global_labels` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_GLOBAL_LABELS` | `GLOBAL_LABELS` | `None` | + +Labels added to all events, with the format `key=value[,key=value[,...]]`. +Any labels set by application via the API will override global labels with the same keys. + + +This feature requires APM Server >= 7.2. + + +
+ +### `disable_log_record_factory` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_DISABLE_LOG_RECORD_FACTORY` | `DISABLE_LOG_RECORD_FACTORY` | `False` | + +By default in python 3, the agent installs a {/* LogRecord factory */} that +automatically adds tracing fields to your log records. Disable this +behavior by setting this to `True`. + +
+ +### `use_elastic_traceparent_header` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `USE_ELASTIC_TRACEPARENT_HEADER` | `True` | + +To enable [distributed tracing](((apm-guide-ref))/apm-distributed-tracing.html), +the agent sets a number of HTTP headers to outgoing requests made with instrumented HTTP libraries. +These headers (`traceparent` and `tracestate`) are defined in the [W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification. + +Additionally, when this setting is set to `True`, the agent will set `elasticapm-traceparent` for backwards compatibility. + +
+ +### `trace_continuation_strategy` + +Dynamic + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` | `TRACE_CONTINUATION_STRATEGY` | `continue` | + +This option allows some control on how the APM agent handles W3C trace-context headers on incoming requests. +By default, the `traceparent` and `tracestate` headers are used per W3C spec for distributed tracing. +However, in certain cases it can be helpful to **not** use the incoming `traceparent` header. +Some example use cases: + +- An Elastic-monitored service is receiving requests with `traceparent` headers from **unmonitored** services. +- An Elastic-monitored service is publicly exposed, and does not want tracing data (trace-ids, sampling decisions) to possibly be spoofed by user requests. + +Valid values are: + +- `'continue'`: The default behavior. An incoming `traceparent` value is used to continue the trace and determine the sampling decision. +- `'restart'`: Always ignores the `traceparent` header of incoming requests. + A new trace-id will be generated and the sampling decision will be made based on `transaction_sample_rate`. + A **span link** will be made to the incoming traceparent. +- `'restart_external'`: If an incoming request includes the `es` vendor flag in `tracestate`, then any 'traceparent' will be considered internal and will be handled as described for `'continue'` above. + Otherwise, any `'traceparent'` is considered external and will be handled as described for `'restart'` above. + +Starting with Elastic Observability 8.2, span links will be visible in trace +views. + +
+ +### `use_elastic_excepthook` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_USE_ELASTIC_EXCEPTHOOK` | `USE_ELASTIC_EXCEPTHOOK` | `False` | + +If set to `True`, the agent will intercept the default `sys.excepthook`, which +allows the agent to collect all uncaught exceptions. + +
+ +### `include_process_args` + +| Environment | Django/Flask | Default | +|---|---|---| +| `ELASTIC_APM_INCLUDE_PROCESS_ARGS` | `INCLUDE_PROCESS_ARGS` | `False` | + +Whether each transaction should have the process arguments attached. Disabled by default to save disk space. + +
+ +## Django-specific configuration + +
+ +### `django_transaction_name_from_route` + +| Environment | Django | Default | +|---|---|---| +| `ELASTIC_APM_DJANGO_TRANSACTION_NAME_FROM_ROUTE` | `DJANGO_TRANSACTION_NAME_FROM_ROUTE` | `False` | + +By default, we use the function or class name of the view as the transaction name. +Starting with Django 2.2, Django makes the route (e.g. `users//`) available on the `request.resolver_match` object. +If you want to use the route instead of the view name as the transaction name, set this config option to `true`. + + +in versions previous to Django 2.2, changing this setting will have no effect. + + +
+ +### `django_autoinsert_middleware` + +| Environment | Django | Default | +|---|---|---| +| `ELASTIC_APM_DJANGO_AUTOINSERT_MIDDLEWARE` | `DJANGO_AUTOINSERT_MIDDLEWARE` | `True` | + +To trace Django requests, the agent uses a middleware, `elasticapm.contrib.django.middleware.TracingMiddleware`. +By default, this middleware is inserted automatically as the first item in `settings.MIDDLEWARES`. +To disable the automatic insertion of the middleware, change this setting to `False`. + +
+ +## Generic Environment variables + +Some environment variables that are not specific to the APM agent can be used to configure the agent. + +
+ +### `HTTP_PROXY` and `HTTPS_PROXY` + +By using `HTTP_PROXY` and `HTTPS_PROXY`, the agent can be instructed to use a proxy to connect to the APM Server. +If both are set, `HTTPS_PROXY` takes precedence. + + +The environment variables are case-insensitive. + + +
+ +### `NO_PROXY` + +To instruct the agent to **not** use a proxy, you can use the `NO_PROXY` environment variable. +You can either set it to a comma-separated list of hosts for which no proxy should be used (e.g. `localhost,example.com`) +or use `*` to match any host. + +This is useful if `HTTP_PROXY` / `HTTPS_PROXY` is set for other reasons than agent / APM Server communication. + +
+ +### `SSL_CERT_FILE` and `SSL_CERT_DIR` + +To tell the agent to use a different SSL certificate, you can use these environment variables. +See also [OpenSSL docs](https://www.openssl.org/docs/manmaster/man7/openssl-env.html#SSL_CERT_DIR-SSL_CERT_FILE). + +Please note that these variables may apply to other SSL/TLS communication in your service, +not just related to the APM agent. + + +These environment variables only take effect if `use_certifi` is set to `False`. + + +
+ +## Configuration formats + +Some options require a unit, either duration or size. +These need to be provided in a specific format. + +
+ +### Duration format + +The _duration_ format is used for options like timeouts. +The unit is provided as a suffix directly after the number–without any separation by whitespace. + +**Example**: `5ms` + +**Supported units** + + * `us` (microseconds) + * `ms` (milliseconds) + * `s` (seconds) + * `m` (minutes) + +
+ +### Size format + +The _size_ format is used for options like maximum buffer sizes. +The unit is provided as suffix directly after the number, without and separation by whitespace. + +**Example**: `10kb` + +**Supported units**: + + * `b` (bytes) + * `kb` (kilobytes) + * `mb` (megabytes) + * `gb` (gigabytes) + + +We use the power-of-two sizing convention, e.g. `1 kilobyte == 1024 bytes` + + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx index ac036c7371..05eaa4b189 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx @@ -5,3 +5,124 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +Getting Elastic APM set up for your Aiohttp Server project is easy, +and there are various ways you can tweak it to fit to your needs. + +
+ +## Installation + +Install the Elastic APM agent using pip: + +```bash +$ pip install elastic-apm +``` + +or add `elastic-apm` to your project's `requirements.txt` file. + +
+ +## Setup + +To set up the agent, you need to initialize it with appropriate settings. + +The settings are configured either via environment variables, +the application's settings, or as initialization arguments. + +You can find a list of all available settings in the Configuration page. + +To initialize the agent for your application using environment variables: + +```python +from aiohttp import web + +from elasticapm.contrib.aiohttp import ElasticAPM + +app = web.Application() + +apm = ElasticAPM(app) +``` + +To configure the agent using `ELASTIC_APM` in your application's settings: + +```python +from aiohttp import web + +from elasticapm.contrib.aiohttp import ElasticAPM + +app = web.Application() + +app['ELASTIC_APM'] = { + 'SERVICE_NAME': '', + 'SECRET_TOKEN': '', +} +apm = ElasticAPM(app) +``` + +
+ +## Usage + +Once you have configured the agent, +it will automatically track transactions and capture uncaught exceptions within aiohttp. + +Capture an arbitrary exception by calling `capture_exception`: + +```python +try: + 1 / 0 +except ZeroDivisionError: + apm.client.capture_exception() +``` + +Log a generic message with `capture_message`: + +```python +apm.client.capture_message('hello, world!') +``` + +
+ +## Performance metrics + +If you've followed the instructions above, the agent has already installed our middleware. +This will measure response times, as well as detailed performance data for all supported technologies. + + +due to the fact that `asyncio` drivers are usually separate from their synchronous counterparts, +specific instrumentation is needed for all drivers. +The support for asynchronous drivers is currently quite limited. + + +
+ +### Ignoring specific routes + +You can use the `TRANSACTIONS_IGNORE_PATTERNS` configuration option to ignore specific routes. +The list given should be a list of regular expressions which are matched against the transaction name: + +```python +app['ELASTIC_APM'] = { + # ... + 'TRANSACTIONS_IGNORE_PATTERNS': ['^OPTIONS ', '/api/'] + # ... +} +``` + +This would ignore any requests using the `OPTIONS` method +and any requests containing `/api/`. + +
+ +## Supported aiohttp and Python versions + +A list of supported aiohttp and {/* Python */} versions can be found on our {/* Supported Technologies */} page. + + +Elastic APM only supports `asyncio` when using Python 3.7+ + + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx index 4b0681b722..505d695820 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx index 1a857d0fd6..b5f9406de4 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx @@ -5,3 +5,117 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +Using an APM solution comes with certain trade-offs, and the Python agent for Elastic APM is no different. +Instrumenting your code, measuring timings, recording context data, etc., all need resources: + + * CPU time + * memory + * bandwidth use + * Elasticsearch storage + +We invested and continue to invest a lot of effort to keep the overhead of using Elastic APM as low as possible. +But because every deployment is different, there are some knobs you can turn to adapt it to your specific needs. + +
+ +## Transaction Sample Rate + +The easiest way to reduce the overhead of the agent is to tell the agent to do less. +If you set the `transaction_sample_rate` to a value below `1.0`, +the agent will randomly sample only a subset of transactions. +Unsampled transactions only record the name of the transaction, the overall transaction time, and the result: + +| Field | Sampled | Unsampled | +|---|---|---| +| Transaction name | yes | yes | +| Duration | yes | yes | +| Result | yes | yes | +| Context | yes | no | +| Tags | yes | no | +| Spans | yes | no | + +Reducing the sample rate to a fraction of all transactions can make a huge difference in all four of the mentioned resource types. + +
+ +## Transaction Queue + +To reduce the load on the APM Server, the agent does not send every transaction up as it happens. +Instead, it queues them up and flushes the queue periodically, or when it reaches a maximum size, using a background thread. + +While this reduces the load on the APM Server (and to a certain extent on the agent), +holding on to the transaction data in a queue uses memory. +If you notice that using the Python agent results in a large increase of memory use, +you can use these settings: + + * `api_request_time` to reduce the time between queue flushes + * `api_request_size` to reduce the maximum size of the queue + +The first setting, `api_request_time`, is helpful if you have a sustained high number of transactions. +The second setting, `api_request_size`, can help if you experience peaks of transactions +(a large number of transactions in a short period of time). + +Keep in mind that reducing the value of either setting will cause the agent to send more HTTP requests to the APM Server, +potentially causing a higher load. + +
+ +## Spans per transaction + +The average amount of spans per transaction can influence how much time the agent spends in each transaction collecting contextual data for each span, +and the storage space needed in Elasticsearch. +In our experience, most _usual_ transactions should have well below 100 spans. +In some cases, however, the number of spans can explode: + + * long-running transactions + * unoptimized code, e.g. doing hundreds of SQL queries in a loop + +To avoid these edge cases overloading both the agent and the APM Server, +the agent stops recording spans when a specified limit is reached. +You can configure this limit by changing the `transaction_max_spans` setting. + +
+ +## Span Stack Trace Collection + +Collecting stack traces for spans can be fairly costly from a performance standpoint. +Stack traces are very useful for pinpointing which part of your code is generating a span; +however, these stack traces are less useful for very short spans (as problematic spans tend to be longer). + +You can define a minimal threshold for span duration +using the `span_stack_trace_min_duration` setting. +If a span's duration is less than this config value, no stack frames will be collected for this span. + +
+ +## Collecting Frame Context + +When a stack trace is captured, the agent will also capture several lines of source code around each frame location in the stack trace. This allows the APM app to give greater insight into where exactly the error or span happens. + +There are four settings you can modify to control this behavior: + +* `source_lines_error_app_frames` +* `source_lines_error_library_frames` +* `source_lines_span_app_frames` +* `source_lines_span_library_frames` + +As you can see, these settings are divided between app frames, which represent your application code, and library frames, which represent the code of your dependencies. Each of these categories are also split into separate error and span settings. + +Reading source files inside a running application can cause a lot of disk I/O, and sending up source lines for each frame will have a network and storage cost that is quite high. Turning down these limits will help prevent excessive memory usage. + +
+ +## Collecting headers and request body + +You can configure the Elastic APM agent to capture headers of both requests and responses (`capture_headers`), +as well as request bodies (`capture_body`). +By default, capturing request bodies is disabled. +Enabling it for transactions may introduce noticeable overhead, as well as increased storage use, depending on the nature of your POST requests. +In most scenarios, we advise against enabling request body capturing for transactions, and only enable it if necessary for errors. + +Capturing request/response headers has less overhead on the agent, but can have an impact on storage use. +If storage use is a problem for you, it might be worth disabling. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx index 56488d5abd..30217e8e5a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx @@ -5,3 +5,673 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +
+ +The Elastic APM Python Agent comes with support for the following frameworks: + + * {/* Django */} + * {/* Flask */} + * Aiohttp Server + * Tornado + * Starlette/FastAPI + * Sanic + * GRPC + +For other frameworks and custom Python code, the agent exposes a set of APIs for integration. + +
+ +## Python + +The following Python versions are supported: + + * 3.6 + * 3.7 + * 3.8 + * 3.9 + * 3.10 + * 3.11 + +
+ +## Django + +We support these Django versions: + + * 1.11 + * 2.0 + * 2.1 + * 2.2 + * 3.0 + * 3.1 + * 3.2 + * 4.0 + +For upcoming Django versions, we generally aim to ensure compatibility starting with the first Release Candidate. + + +we currently don't support Django running in ASGI mode. + + +
+ +## Flask + +We support these Flask versions: + + * 0.10 (Deprecated) + * 0.11 (Deprecated) + * 0.12 (Deprecated) + * 1.0 + * 1.1 + * 2.0 + +
+ +## Aiohttp Server + +We support these aiohttp versions: + + * 3.0+ + +
+ +## Tornado + +We support these tornado versions: + + * 6.0+ + +
+ +## Sanic + +We support these sanic versions: + + * 20.12.2+ + +
+ +## Starlette/FastAPI + +We support these Starlette versions: + + * 0.13.0+ + +Any FastAPI version which uses a supported Starlette version should also +be supported. + +
+ +## GRPC + +We support these `grpcio` versions: + + * 1.24.0+ + +
+ +# Automatic Instrumentation + +The Python APM agent comes with automatic instrumentation of various 3rd party modules and standard library modules. + +
+ +## Scheduling + +
+ +#### Celery + +We support these Celery versions: + +* 3.x +* 4.x + +Celery tasks will be recorded automatically with Django and Flask only. + +
+ +## Databases + +
+ +### Elasticsearch + +Instrumented methods: + + * `elasticsearch.transport.Transport.perform_request` + * `elasticsearch.connection.http_urllib3.Urllib3HttpConnection.perform_request` + * `elasticsearch.connection.http_requests.RequestsHttpConnection.perform_request` + * `elasticsearch._async.transport.AsyncTransport.perform_request` + * `elasticsearch_async.connection.AIOHttpConnection.perform_request` + +Additionally, the instrumentation wraps the following methods of the `Elasticsearch` client class: + + * `elasticsearch.client.Elasticsearch.delete_by_query` + * `elasticsearch.client.Elasticsearch.search` + * `elasticsearch.client.Elasticsearch.count` + * `elasticsearch.client.Elasticsearch.update` + +Collected trace data: + + * the query string (if available) + * the `query` element from the request body (if available) + * the response status code + * the count of affected rows (if available) + +We recommend using keyword arguments only with elasticsearch-py, as recommended by +[the elasticsearch-py docs](https://elasticsearch-py.readthedocs.io/en/master/api.html#api-documentation). +If you are using positional arguments, we will be unable to gather the `query` +element from the request body. + +
+ +### SQLite + +Instrumented methods: + + * `sqlite3.connect` + * `sqlite3.dbapi2.connect` + * `pysqlite2.dbapi2.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### MySQLdb + +Library: `MySQLdb` + +Instrumented methods: + + * `MySQLdb.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### mysql-connector + +Library: `mysql-connector-python` + +Instrumented methods: + + * `mysql.connector.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### pymysql + +Library: `pymysql` + +Instrumented methods: + + * `pymysql.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### aiomysql + +Library: `aiomysql` + +Instrumented methods: + + * `aiomysql.cursors.Cursor.execute` + +Collected trace data: + + * parametrized SQL query + +
+ +### PostgreSQL + +Library: `psycopg2`, `psycopg2-binary` (`>=2.9`) + +Instrumented methods: + + * `psycopg2.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### aiopg + +Library: `aiopg` (`>=1.0`) + +Instrumented methods: + + * `aiopg.cursor.Cursor.execute` + * `aiopg.cursor.Cursor.callproc` + +Collected trace data: + + * parametrized SQL query + +
+ +### asyncpg + +Library: `asyncpg` (`>=0.20`) + +Instrumented methods: + + * `asyncpg.connection.Connection.execute` + * `asyncpg.connection.Connection.executemany` + +Collected trace data: + + * parametrized SQL query + +
+ +### PyODBC + +Library: `pyodbc`, (`>=4.0`) + +Instrumented methods: + + * `pyodbc.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### MS-SQL + +Library: `pymssql`, (`>=2.1.0`) + +Instrumented methods: + + * `pymssql.connect` + +The instrumented `connect` method returns a wrapped connection/cursor which instruments the actual `Cursor.execute` calls. + +Collected trace data: + + * parametrized SQL query + +
+ +### MongoDB + +Library: `pymongo`, `>=2.9,<3.8` + +Instrumented methods: + + * `pymongo.collection.Collection.aggregate` + * `pymongo.collection.Collection.bulk_write` + * `pymongo.collection.Collection.count` + * `pymongo.collection.Collection.create_index` + * `pymongo.collection.Collection.create_indexes` + * `pymongo.collection.Collection.delete_many` + * `pymongo.collection.Collection.delete_one` + * `pymongo.collection.Collection.distinct` + * `pymongo.collection.Collection.drop` + * `pymongo.collection.Collection.drop_index` + * `pymongo.collection.Collection.drop_indexes` + * `pymongo.collection.Collection.ensure_index` + * `pymongo.collection.Collection.find_and_modify` + * `pymongo.collection.Collection.find_one` + * `pymongo.collection.Collection.find_one_and_delete` + * `pymongo.collection.Collection.find_one_and_replace` + * `pymongo.collection.Collection.find_one_and_update` + * `pymongo.collection.Collection.group` + * `pymongo.collection.Collection.inline_map_reduce` + * `pymongo.collection.Collection.insert` + * `pymongo.collection.Collection.insert_many` + * `pymongo.collection.Collection.insert_one` + * `pymongo.collection.Collection.map_reduce` + * `pymongo.collection.Collection.reindex` + * `pymongo.collection.Collection.remove` + * `pymongo.collection.Collection.rename` + * `pymongo.collection.Collection.replace_one` + * `pymongo.collection.Collection.save` + * `pymongo.collection.Collection.update` + * `pymongo.collection.Collection.update_many` + * `pymongo.collection.Collection.update_one` + +Collected trace data: + + * database name + * method name + +
+ +### Redis + +Library: `redis` (`>=2.8`) + +Instrumented methods: + + * `redis.client.Redis.execute_command` + * `redis.client.Pipeline.execute` + +Collected trace data: + + * Redis command name + +
+ +### aioredis + +Library: `aioredis` (`<2.0`) + +Instrumented methods: + + * `aioredis.pool.ConnectionsPool.execute` + * `aioredis.commands.transaction.Pipeline.execute` + * `aioredis.connection.RedisConnection.execute` + +Collected trace data: + + * Redis command name + +
+ +### Cassandra + +Library: `cassandra-driver` (`>=3.4,<4.0`) + +Instrumented methods: + + * `cassandra.cluster.Session.execute` + * `cassandra.cluster.Cluster.connect` + +Collected trace data: + + * CQL query + +
+ +### Python Memcache + +Library: `python-memcached` (`>=1.51`) + +Instrumented methods: + +* `memcache.Client.add` +* `memcache.Client.append` +* `memcache.Client.cas` +* `memcache.Client.decr` +* `memcache.Client.delete` +* `memcache.Client.delete_multi` +* `memcache.Client.disconnect_all` +* `memcache.Client.flush_all` +* `memcache.Client.get` +* `memcache.Client.get_multi` +* `memcache.Client.get_slabs` +* `memcache.Client.get_stats` +* `memcache.Client.gets` +* `memcache.Client.incr` +* `memcache.Client.prepend` +* `memcache.Client.replace` +* `memcache.Client.set` +* `memcache.Client.set_multi` +* `memcache.Client.touch` + +Collected trace data: + +* Destination (address and port) + +
+ +### pymemcache + +Library: `pymemcache` (`>=3.0`) + +Instrumented methods: + +* `pymemcache.client.base.Client.add` +* `pymemcache.client.base.Client.append` +* `pymemcache.client.base.Client.cas` +* `pymemcache.client.base.Client.decr` +* `pymemcache.client.base.Client.delete` +* `pymemcache.client.base.Client.delete_many` +* `pymemcache.client.base.Client.delete_multi` +* `pymemcache.client.base.Client.flush_all` +* `pymemcache.client.base.Client.get` +* `pymemcache.client.base.Client.get_many` +* `pymemcache.client.base.Client.get_multi` +* `pymemcache.client.base.Client.gets` +* `pymemcache.client.base.Client.gets_many` +* `pymemcache.client.base.Client.incr` +* `pymemcache.client.base.Client.prepend` +* `pymemcache.client.base.Client.quit` +* `pymemcache.client.base.Client.replace` +* `pymemcache.client.base.Client.set` +* `pymemcache.client.base.Client.set_many` +* `pymemcache.client.base.Client.set_multi` +* `pymemcache.client.base.Client.stats` +* `pymemcache.client.base.Client.touch` + +Collected trace data: + +* Destination (address and port) + +
+ +### kafka-python + +Library: `kafka-python` (`>=2.0`) + +Instrumented methods: + + * `kafka.KafkaProducer.send`, + * `kafka.KafkaConsumer.poll`, + * `kafka.KafkaConsumer.\\__next__` + +Collected trace data: + + * Destination (address and port) + * topic (if applicable) + +
+ +## External HTTP requests + +
+ +### Standard library + +Library: `urllib2` (Python 2) / `urllib.request` (Python 3) + +Instrumented methods: + + * `urllib2.AbstractHTTPHandler.do_open` / `urllib.request.AbstractHTTPHandler.do_open` + +Collected trace data: + + * HTTP method + * requested URL + +
+ +### urllib3 + +Library: `urllib3` + +Instrumented methods: + + * `urllib3.connectionpool.HTTPConnectionPool.urlopen` + +Additionally, we instrumented vendored instances of urllib3 in the following libraries: + + * `requests` + * `botocore` + +Both libraries have "unvendored" urllib3 in more recent versions, we recommend to use the newest versions. + +Collected trace data: + + * HTTP method + * requested URL + +
+ +### requests + +Instrumented methods: + + * `requests.sessions.Session.send` + +Collected trace data: + + * HTTP method + * requested URL + +
+ +### AIOHTTP Client + +Instrumented methods: + + * `aiohttp.client.ClientSession._request` + +Collected trace data: + + * HTTP method + * requested URL + +
+ +### httpx + +Instrumented methods: + + * `httpx.Client.send + +Collected trace data: + + * HTTP method + * requested URL + +
+ +## Services + +
+ +### AWS Boto3 / Botocore + +Library: `boto3` (`>=1.0`) + +Instrumented methods: + + * `botocore.client.BaseClient._make_api_call` + +Collected trace data for all services: + + * AWS region (e.g. `eu-central-1`) + * AWS service name (e.g. `s3`) + * operation name (e.g. `ListBuckets`) + +Additionally, some services collect more specific data + +
+ +### AWS Aiobotocore + +Library: `aiobotocore` (`>=2.2.0`) + +Instrumented methods: + + * `aiobotocore.client.BaseClient._make_api_call` + +Collected trace data for all services: + + * AWS region (e.g. `eu-central-1`) + * AWS service name (e.g. `s3`) + * operation name (e.g. `ListBuckets`) + +Additionally, some services collect more specific data + +
+ +#### S3 + + * Bucket name + +
+ +#### DynamoDB + + * Table name + +
+ +#### SNS + + * Topic name + +
+ +#### SQS + + * Queue name + +
+ +## Template Engines + +
+ +### Django Template Language + +Library: `Django` (see Django for supported versions) + +Instrumented methods: + + * `django.template.Template.render` + +Collected trace data: + + * template name + +
+ +### Jinja2 + +Library: `jinja2` + +Instrumented methods: + + * `jinja2.Template.render` + +Collected trace data: + + * template name diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx index 91fe3e8c81..7b4ff69d19 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx @@ -5,3 +5,36 @@ title: Python # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM Python agent sends performance metrics and error logs to the APM Server. +It has built-in support for Django and Flask performance metrics and error logging, as well as generic support of other WSGI frameworks for error logging. + +
+ +## How does the Agent work? + +The Python Agent instruments your application to collect APM events in a few different ways: + +To collect data about incoming requests and background tasks, the Agent integrates with supported technologies to make use of hooks and signals provided by the framework. +These framework integrations require limited code changes in your application. + +To collect data from database drivers, HTTP libraries etc., +we instrument certain functions and methods in these libraries. +Instrumentations are set up automatically and do not require any code changes. + +In addition to APM and error data, +the Python agent also collects system and application metrics in regular intervals. +This collection happens in a background thread that is started by the agent. + +More detailed information on how the Agent works can be found in the {/* advanced topics */}. + +
+ +## Additional components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx index b720922552..714be9deae 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx @@ -5,3 +5,484 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at +[elastic.co](https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html) + + + +
+ +Although most usage is covered automatically, Elastic APM also has a public +API that allows custom usage. + +
+ +## Agent life cycle + +Controlling when the agent starts and stops. + +
+ +### `ElasticAPM.start` + +To create and start an ElasticAPM agent use `ElasticAPM.start`: + +```ruby +ElasticAPM.start(server_url: 'http://localhost:8200') +``` + + * `config`: An optional hash or `ElasticAPM::Config` instance with configuration + options. See Configuration. + +If you are using {/* Ruby on Rails */} this is done automatically for you. +If you choose not to require the `elastic_apm` gem and instead want to start the +agent and hook into Rails manually, see hooking into Rails explicitly. +If you're not using Rails, see {/* Getting started with Rack */}. + +
+ +### `ElasticAPM.stop` + +Stop the currently running agent. Use this inside `at_exit` in your +{/* Rack app */} to gracefully shut down. + +
+ +### `ElasticAPM.restart` + +If the agent is already running, this method will stop and start the agent. + +If the agent is not already running, this method will start the agent. + +A config can be passed to the method that will be used to start the agent. If the agent +is already running and no config is passed to the `#restart` method, the running agent's +config will be used. + +
+ +### `ElasticAPM.running?` + +Returns whether the ElasticAPM Agent is currently running. + +
+ +### `ElasticAPM.agent` + +Returns the currently running agent or nil. + +## Instrumentation + +
+ +### `ElasticAPM.current_transaction` + +Returns the current `ElasticAPM::Transaction` or nil. + +
+ +### `ElasticAPM.start_transaction` + +Start a _transaction_ eg. an incoming web request or a background job. + +```ruby +# call with block +ElasticAPM.start_transaction('Name') +do_work # ... +ElasticAPM.end_transaction('result') +``` + +Arguments: + + * `name`: A name for your transaction. Transactions are grouped by name. **Required**. + * `type`: A `type` for your transaction eg. `db.postgresql.sql`. + * `context:`: An optional Context used to enrich the + transaction with information about the current request. + + * `trace_context:`: An optional `TraceContext` object for Distributed Tracing. + +Returns the transaction. + +
+ +### `ElasticAPM.end_transaction` + +Ends the currently running transaction. + +Arguments: + + * `result`: A `String` result of the transaction, eg. `'success'`. + +
+ +### `ElasticAPM.with_transaction` + +Wrap a block in a Transaction, starting and ending around the block + +```ruby +ElasticAPM.with_transaction 'Do things' do |transaction| + do_work # ... + + transaction.result = 'success' +end +``` + +Arguments: + + * `name`: A name for your transaction. Transactions are grouped by name. **Required**. + * `type`: A `type` for your transaction eg. `db.postgresql.sql`. + * `context:`: An optional Context used to enrich the + transaction with information about the current request. + + * `trace_context:`: An optional `TraceContext` object for Distributed Tracing. + * `&block`: A block to wrap. Optionally yields the transaction. + +Returns the return value of the given block. + +
+ +### `ElasticAPM.start_span` + +Start a new span. + +```ruby +ElasticAPM.with_transaction 'Do things' do + ElasticAPM.start_span 'Do one of the things' + Database.query # ... + ElasticAPM.end_span +end +``` + +Arguments: + + * `name`: A name for your span. **Required**. + * `type`: The type of span eg. `db`. + * `subtype`: The subtype of span eg. `postgresql`. + * `action`: The action type of span eg. `connect` or `query`. + * `context`: An instance of `Span::Context`. + * `include_stacktrace`: Whether or not to collect a Stacktrace. + * `trace_context:`: An optional `TraceContext` object for Distributed Tracing. + * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread. + * `sync:`: An boolean to indicate whether the span is created synchronously or not. + * `&block`: An optional block to wrap with the span. + The block is passed the span as an optional argument. + +Returns the created span. + +If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `start_span` method. +You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous. This has no effect other than being queryable in Elasticsearch. + +```ruby +transaction = ElasticAPM.current_transaction # or start one with `.start_transaction` +Thread.new do + ElasticAPM.start_span( + 'job 1', + parent: transaction, + sync: false + ) { Worker.perform } + ElasticAPM.end_span +end +``` + +
+ +### `ElasticAPM.end_span` + +Ends the currently running span. + +
+ +### `ElasticAPM.with_span` + +Wraps a block in a Span. + +Arguments: + + * `name`: A name for your span. **Required**. + * `type`: The type of span eg. `db`. + * `subtype`: The subtype of span eg. `postgresql`. + * `action`: The action type of span eg. `connect` or `query`. + * `context`: An instance of `Span::Context`. + * `include_stacktrace`: Whether or not to collect a Stacktrace. + * `trace_context:`: An optional `TraceContext` object for Distributed Tracing. + * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread. + * `sync:`: An boolean to indicate whether the span is created synchronously or not. + * `&block`: An optional block to wrap with the span. + The block is passed the span as an optional argument. + +Returns the return value of the given block. + +If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `with_span` method. +You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous. + +```ruby +transaction = ElasticAPM.current_transaction # or start one with `.start_transaction` +Thread.new do + ElasticAPM.with_span( + 'job 1', + parent: transaction, + sync: false + ) { Worker.perform } +end +``` + +
+ +### `ElasticAPM.build_context` + +Build a new _Context_ from a Rack `env`. + +A context provides information about the current request, response, user and more. + +Arguments: + + * `rack_env`: An instance of Rack::Env + * `for_type`: Symbol representing type of event, eg. `:transaction` or `error` + +Returns the built context. + +
+ +## Rails + +Start the agent and hook into Rails manually. This is useful if you skip requiring +the gem and using the `Railtie`. + +```ruby +ElasticAPM::Rails.start(server_url: 'http://localhost:8200') +``` + +
+ +## Sinatra + +Start the agent and hook into Sinatra. + +```ruby +ElasticAPM::Sinatra.start(MySinatraApp, server_url: 'http://localhost:8200') +``` + +
+ +## Grape + +Start the agent and hook into Grape. + +```ruby +ElasticAPM::Grape.start(MyGrapeApp, server_url: 'http://localhost:8200') +``` + +## Errors + +
+ +### `ElasticAPM.report` + +Send an `Exception` to Elastic APM. + +If reported inside a transaction, the context from that will be added. + +```ruby +begin + do_a_thing_and_fail +rescue Exception => e + ElasticAPM.report(e) +end +``` + +Arguments: + + * `exception`: An instance of `Exception`. **Required**. + * `handled`: Whether the error was _handled_ eg. wasn't rescued and was represented + to the user. Default: `true`. + +Returns `[String]` ID of the generated `[ElasticAPM::Error]` object. + +
+ +### `ElasticAPM.report_message` + +Send a custom message to Elastic APM. + +If reported inside a transaction, the context from that will be added. + +```ruby +ElasticAPM.report_message('This should probably never happen?!') +``` + +Arguments: + + * `message`: A custom error string. **Required**. + +Returns `[String]` ID of the generated `[ElasticAPM::Error]` object. + +
+ +## Context + +
+ +### `ElasticAPM.set_label` + +Add a label to the current transaction. +Labels are basic key-value pairs that are indexed in your Elasticsearch database and therefore searchable. +The value can be a string, nil, numeric or boolean. + + +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +```ruby +before_action do + ElasticAPM.set_label(:company_id, current_user.company.id) +end +``` + +Arguments: + + * `key`: A string key. Note that `.`, `*` or `"` will be converted to `_`. + * `value`: A value. + +Returns the set `value`. + + +Be aware that labels are indexed in Elasticsearch. Using too many unique keys will result in **https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]**. + + +
+ +### `ElasticAPM.set_custom_context` + +Add custom context to the current transaction. +Use this to further specify a context that will help you track or diagnose what's +going on inside your app. + + +Before using custom context, ensure you understand the different types of +[metadata](((apm-guide-ref))/data-model-metadata.html) that are available. + + +If called several times during a transaction the custom context will be destructively +merged with `merge!`. + +```ruby +before_action do + ElasticAPM.set_custom_context(company: current_user.company.to_h) +end +``` + +Arguments: + + * `context`: A hash of JSON-compatible key-values. Can be nested. + +Returns current custom context. + +
+ +### `ElasticAPM.set_user` + +Add the current user to the current transaction's context. + +Arguments: + + * `user`: An object representing the user + +Returns the given user + +## Data + +
+ +### `ElasticAPM.add_filter` + +Provide a filter to transform payloads before sending. + +Arguments: + + * `key`: A unique key identifying the filter + * `callable`: An object or proc (responds to `.call(payload)`) + +Return the altered payload. + +If `nil` is returned all subsequent filters will be skipped and the post request cancelled. + +Example: + +```ruby +ElasticAPM.add_filter(:filter_pings) do |payload| + payload[:transactions]&.reject! do |t| + t[:name] == 'PingsController#index' + end + payload +end +``` + +
+ +## Transaction + +`ElasticAPM.transaction` returns a `Transaction` (if the agent is running). + +### Properties + +- `name`: String +- `type`: String +- `result`: String +- `outcome`: String ('unknown', 'success', 'failure', nil) +- `trace_id`: String (readonly) + +
+ +### `#sampled?` + +Whether the transaction is _sampled_ eg. it includes stacktraces for its spans. + +
+ +### `#ensure_parent_id` + +If the transaction does not have a parent-ID yet, calling this method generates +a new ID, sets it as the parent-ID of this transaction, and returns it as a +`String`. + +This enables the correlation of the spans the JavaScript Real User Monitoring +(RUM) agent creates for the initial page load with the transaction of the +backend service. + +If your service generates the HTML page dynamically, initializing the +JavaScript RUM agent with the value of this method allows analyzing the time +spent in the browser vs in the backend services. + +To enable the JavaScript RUM agent, initialize the RUM agent with the Ruby +agent's current transaction: + +```html + + +``` +See the [JavaScript RUM agent documentation](((apm-rum-ref))) for more information. + +
+ +## Span + +### Properties + +- `name`: String +- `type`: String diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx index 0d4416124c..cde4a34475 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx @@ -5,3 +5,853 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at +[elastic.co](https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html). + + + +
+ +There are several ways to configure how Elastic APM behaves. +We recommend using a `config/elastic_apm.yml` file: + +```yaml +server_url: 'http://localhost:8200' +secret_token: <%= ENV["VERY_SECRET_TOKEN"] %> +``` + +Some options can be set with `ENV` variables. +When using this method, strings are split by comma, e.g., +`ELASTIC_APM_SANITIZE_FIELD_NAMES="a,b" # => [/a/, /b/]`. + +
+ +## Configuration precedence + +Options are applied in the following order (last one wins): + +1. Defaults +1. Arguments to `ElasticAPM.start` / `Config.new` +1. Config file, e.g., `config/elastic_apm.yml` +1. Environment variables +1. [Central configuration](((apm-app-ref))/agent-configuration.html) + (supported options are marked with Dynamic ) + +
+ +## Dynamic configuration + +Configuration options marked with the Dynamic badge can be changed at runtime +when set from a supported source. + +The Agent supports [Central configuration](((apm-app-ref))/agent-configuration.html), +which allows you to fine-tune certain configurations via the APM app. +This feature is enabled in the Agent by default, with `central_config`. + +## Ruby on Rails + +When using Rails, it's possible to specify options inside +`config/application.rb`: + +```ruby +# config/application.rb +config.elastic_apm.service_name = 'MyApp' +``` + +## Sinatra and Rack + +When using Sinatra and Rack, you can configure when starting +the agent: + +```ruby +# config.ru or similar +ElasticAPM.start( + app: MyApp, + service_name: 'SomeOtherName' +) +``` + +Alternatively, use the `ElasticAPM::Sinatra.start` API: + +```ruby +# config.ru or similar +ElasticAPM::Sinatra.start( + MyApp, + service_name: 'SomeOtherName' +) +``` + +See {/* Getting started with Rack */}. + +## Grape and Rack + +When using Grape and Rack (without Rails), configure when starting +the agent: + +```ruby +# config.ru or similar +ElasticAPM::Grape.start( + MyApp, + service_name: 'SomeOtherName' +) +``` + +See {/* Getting started with Rack */}. + +## Options + +
+ +### `config_file` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_CONFIG_FILE` | `config_file` | `config/elastic_apm.yml` | + +The path to the configuration YAML-file. +Elastic APM will load config options from this if the file exists. +The file will be evaluated as ERB, so you can include `ENV` variables like in +your `database.yml`, eg: + +```ruby +secret_token: <%= ENV['VERY_SECRET_TOKEN'] %> +``` + +
+ +### `server_url` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_SERVER_URL` | `server_url` | `'http://localhost:8200'` | + +The URL for your APM Server. +The URL must be fully qualified, including protocol (`http` or `https`) +and port. + +
+ +### `secret_token` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SECRET_TOKEN` | `secret_token` | `nil` | A random string | + +This string is used to ensure that only your agents can send data to your APM server. +Both the agents and the APM server have to be configured with the same secret token. +Here's an example that generates a secure secret token: + +```bash +ruby -r securerandom -e 'print SecureRandom.uuid' +``` + + +Secret tokens only provide any real security if your APM server uses TLS. + + +
+ +### `api_key` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_API_KEY` | `api_key` | `nil` | A base64-encoded string | + +This base64-encoded string is used to ensure that only your agents can send data to your APM server. +The API key must be created using the [APM server command-line tool](((apm-guide-ref))/api-key.html). + + +API keys only provide any real security if your APM server uses TLS. + + +
+ +### `api_buffer_size` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_API_BUFFER_SIZE` | `api_buffer_size` | `256` | + +The maximum amount of objects kept in queue before sending to APM Server. + +If you hit the limit, consider increasing the agent's worker pool size. +If you don't, the agent may have trouble connecting to APM Server. +The logs should tell you what went wrong. + +
+ +### `api_request_size` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_API_REQUEST_SIZE` | `api_request_size` | `"750kb"` | + +The maximum amount of bytes sent over one request to APM Server. The agent will open a new request when this limit is reached. + +This must be provided in **size format**. + +
+ +### `api_request_time` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_API_REQUEST_TIME` | `api_request_time` | `"10s"` | + +The maximum duration of a single streaming request to APM Server before opening +a new one. + +The APM Server has its own limit of 30 seconds before it will close requests. +This must be provided in **duration format**. + +
+ +### `breakdown-metrics` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_BREAKDOWN_METRICS` | `breakdown_metrics` | `true` | + +Enable or disable the tracking and collection of breakdown metrics. +Setting this to `False` disables the tracking of breakdown metrics, which can reduce the overhead of the agent. + + +This feature requires APM Server and Kibana >= 7.3. + + +
+ +### `capture_body` + +Dynamic + +| | | | | +|---|---|---|---| +| Environment | `Config` key | Default | Example | +| `ELASTIC_APM_CAPTURE_BODY` | `capture_body` | `"off"` | `"all"` | + +The Ruby agent can optionally capture the request body (e.g. `POST` variables or JSON data) for transactions that are HTTP requests. + +Possible values: `"errors"`, `"transactions"`, `"all"`, `"off"`. + +If the request has a body and this setting is disabled, the body will be shown as `[SKIPPED]`. + + +Request bodies often contain sensitive values like passwords and credit card numbers. +We try to strip sensitive looking data from form bodies but don't touch text bodies like JSON. +If your service handles data like this, we advise to only enable this feature with care. + + +
+ +### `capture_headers` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_CAPTURE_HEADERS` | `capture_headers` | `true` | + +This indicates whether or not to attach the request headers to transactions and errors. + +
+ +### `capture_elasticsearch_queries` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_CAPTURE_ELASTICSEARCH_QUERIES` | `capture_elasticsearch_queries` | `false` | + +This indicates whether or not to capture the body from requests in Elasticsearch. + +
+ +### `capture_env` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_CAPTURE_ENV` | `capture_env` | `true` | + +This indicates whether or not to attach `ENV` from Rack to transactions and errors. + +
+ +### `central_config` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_CENTRAL_CONFIG` | `central_config` | `true` | + +This enables [APM Agent Configuration via Kibana](((apm-app-ref))/agent-configuration.html). +If set to `true`, the client will poll the APM Server regularly for new agent configuration. + +Usually APM Server determines how often to poll, but if not, set the default interval is 5 minutes. + + +This feature requires APM Server v7.3 or later and that the APM Server is configured with `kibana.enabled: true`. + + +
+ +### `cloud_provider` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_CLOUD_PROVIDER` | `cloud_provider` | `"auto"` | + +Specify the cloud provider for metadata collection. +This defaults to `"auto"`, which means the agent uses trial and +error to collect metadata from all supported cloud providers. + +Valid options are `"auto"`, `"aws"`, `"gcp"`, `"azure"`, and `"none"`. +If set to `"none"`, no cloud metadata will be collected. +If set to any of `"aws"`, `"gcp"`, or `"azure"`, +attempts to collect metadata will only be performed from the chosen provider. + +
+ +### `disable_metrics` +| | | | | +|---|---|---|---| +| Environment | `Config` key | Default | Example | +| `ELASTIC_APM_DISABLE_METRICS` | `disable_metrics` | [] | `"*.cpu.*,system.memory.total"` | + +A comma-separated list of dotted metrics names that should not be sent to the APM Server. +You can use `*` to match multiple metrics. +Matching is not case sensitive. + +
+ +### `disable_send` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_DISABLE_SEND` | `disable_send` | `false` | + +This disables sending payloads to APM Server. + +
+ +### `disable_start_message` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_DISABLE_START_MESSAGE` | `disable_start_message` | `false` | + +This disables the agents startup message announcing itself. + +
+ +### `disable_instrumentations` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_DISABLE_INSTRUMENTATIONS` | `disable_instrumentations` | `['json']` | + +Elastic APM automatically instruments select third-party libraries. +Use this option to disable any of these. + +Get an array of enabled instrumentations with `ElasticAPM.agent.config.enabled_instrumentations`. + +
+ +### `enabled` +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_ENABLED` | `enabled` | `true` | + +Indicates whether or not to start the agent. +If `enabled` is `false`, `ElasticAPM.start` will do nothing and all calls to the root API will return `nil`. + +
+ +### `environment` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_ENVIRONMENT` | `environment` | From `ENV` | `"production"` | + +The name of the environment this service is deployed in, +e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. +Be consistent when naming environments across agents. +See [environment selector](((apm-app-ref))/filters.html#environment-selector) in the APM app for more information. + +Defaults to `ENV['RAILS_ENV'] || ENV['RACK_ENV']`. + + +This feature is fully supported in the APM app in Kibana versions >= 7.2. +You must use the query bar to filter for a specific environment in versions prior to 7.2. + + +
+ +### `filter_exception_types` +| | | | | +|---|---|---|---| +| Environment | `Config` key | Default | Example | +| N/A | `filter_exception_types` | `[]` | `[MyApp::Errors::IgnoredError]` | + +Use this to filter error tracking for specific error constants. + +
+ +### `framework_name` +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_FRAMEWORK_NAME` | `framework_name` | Depending on framework | + +The name of the used framework. +For Rails or Sinatra, this defaults to `Ruby on Rails` and `Sinatra` respectively, +otherwise defaults to `nil`. + +
+ +### `framework_version` +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_FRAMEWORK_VERSION` | `framework_version` | Depending on framework | + +The version number of the used framework. +For Ruby on Rails and Sinatra, this defaults to the used version of the framework, +otherwise, the default is `nil`. + +
+ +### `global_labels` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_GLOBAL_LABELS` | `global_labels` | `nil` | `dept=engineering,rack=number8` | + +Labels added to all events, with the format key=value[,key=value[,...]]. + + +This option requires APM Server 7.2 or greater, and will have no effect when using older +server versions. + + +
+ +### `hostname` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_HOSTNAME` | `hostname` | `hostname` | `app-server01.example.com` | + +The host name to use when sending error and transaction data to the APM server. + +
+ +### `ignore_url_patterns` +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_IGNORE_URL_PATTERNS` | `ignore_url_patterns` | `[]` | `['^/ping', %r{^/admin}]` | + +Use this option to ignore certain URL patterns such as healthchecks or admin sections. + +_Ignoring_ in this context means _don't wrap in a Transaction_. +Errors will still be reported. + +Use a comma separated string when setting this option via `ENV`. +Eg. `ELASTIC_APM_IGNORE_URL_PATTERNS="a,b" # => [/a/, /b/]` + +
+ +### `instrument` +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_INSTRUMENT` | `instrument` | `true` | `0` | + +Use this option to ignore certain URL patterns such as healthchecks or admin sections. + +
+ +### `instrumented_rake_tasks` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_INSTRUMENTED_RAKE_TASKS` | `instrumented_rake_tasks` | `[]` | `['my_task']` | + +Elastic APM can instrument your Rake tasks. This is an opt-in field, as they are used are for a multitude of things. + +
+ +### `log_ecs_reformatting` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_LOG_ECS_REFORMATTING` | `log_ecs_reformatting` | `off` | + +This is an experimental option that configures the agent to use the logger from the `ecs-logging` gem. The two +valid options are `off` and `override`. + +Setting this option to `override` will set the agent logger to a `EcsLogging::Logger` instance and all logged output +will be in ECS-compatible json. + +The `ecs-logging` gem must be installed before the agent is started. If `log_ecs_reformatting` is set to `override`, +the agent will attempt to require the gem and if it cannot be loaded, it will fall back to using the standard Ruby +`::Logger` and log the load error. + +Note that if you're using Rails, the agent will ignore this option and use the Rails logger. If you want to use a +`EcsLogging::Logger` when using Rails, set the agent's logger config option explicitly to a `EcsLogging::Logger` +instance. + +
+ +### `log_level` + +Dynamic + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_LOG_LEVEL` | `log_level` | `Logger::INFO # => 1` | + +By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails. + +
+ +### `log_path` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_LOG_PATH` | `log_path` | `nil` | `log/elastic_apm.log` | + +A path to a log file. + +By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails. + +If `log_path` is specified, this will override `Rails.log` to point to that path instead. + +This should support both absolute and relative paths. Please be sure the directory exists. + +
+ +### `logger` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| N/A | `logger` | Depends | `Logger.new('path/to_file.log')` | + +By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails. + +Use this to provide another logger. This is expected to have the same API as Ruby's built-in `Logger`. + +
+ +### `metrics_interval` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_METRICS_INTERVAL` | `metrics_interval` | `'30s'` | + +Specify the interval for reporting metrics to APM Server. +The interval should be in seconds, +or include a time suffix. + +To disable metrics reporting, +set the interval to `0`. + +
+ +### `pool_size` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_POOL_SIZE` | `pool_size` | `1` | `2` | + +Elastic APM uses a thread pool to send its data to APM Server. + +This makes sure the agent doesn't block the main thread any more than necessary. + +If you have high load and get warnings about the buffer being full, increasing +the worker pool size might help. + +
+ +### `proxy_address` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_PROXY_ADDRESS` | `proxy_address` | `nil` | `"example.com"` | + +An address to use as a proxy for the HTTP client. + +Options available are: + +- `proxy_address` +- `proxy_headers` +- `proxy_password` +- `proxy_port` +- `proxy_username` + +There are also `ENV` version of these following the same pattern of putting `ELASTIC_APM_` in front. + +See [Http.rb's docs](https://github.com/httprb/http/wiki/Proxy-Support). + +
+ +### `recording` + +Dynamic + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_RECORDING` | `recording` | `true` | + +Enable or disable the recording of events. +If set to `false`, then the agent does not create or send any events to the Elastic APM server, +and instrumentation overhead is minimized. The agent continues to poll the server for configuration changes +when this option is false. + +
+ +### `sanitize_field_names` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `sanitize_field_names` | `"password,passwd,pwd,secret,*key,*token*,*session*,*credit*,*card*,*auth*,set-cookie"` | `Auth*tion,abc*,*xyz` | + +Sometimes it is necessary to sanitize the data sent to Elastic APM to remove sensitive values. + +Configure a list of wildcard patterns of field names which should be sanitized. These apply to HTTP headers and bodies, if they're being captured. + +Supports the wildcard `*`, which matches zero or more characters. +Examples: `/foo/*/bar/*/baz*`, `*foo*`. +Matching is case insensitive. + +
+ +### `service_name` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVICE_NAME` | `service_name` | App's name | `MyApp` | + +The name of your service. This is used to group the errors and transactions of your service and is +the primary filter in the Elastic APM user interface. + +If you're using Ruby on Rails this will default to your app's name. +If you're using Sinatra it will default to the name of your app's class. + + +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. +In other words, it must only contain characters from the ASCII +alphabet, numbers, dashes, underscores, and spaces. + + +
+ +### `service_node_name` + + [options="header"] +| | | | | +|---|---|---|---| +| Environment | `Config` key | Default | Example | +| `ELASTIC_APM_SERVICE_NODE_NAME` | `service_node_name` | `nil` | `"my-app-1"` | + +The name of the given service node. This is optional, and if omitted, the APM +Server will fall back on `system.container.id` if available, and +`host.name` if necessary. + +This option allows you to set the node name manually to ensure it's unique and meaningful. + +
+ +### `service_version` +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVICE_VERSION` | `service_version` | `git` sha | A string indicating the version of the deployed service | + +The deployed version of your service. +This defaults to `git rev-parse --verify HEAD`. + +
+ +### `source_lines_error_app_frames` + +
+ +### `source_lines_error_library_frames` + +
+ +### `source_lines_span_app_frames` + +
+ +### `source_lines_span_library_frames` + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES` | `source_lines_error_app_frames` | `5` | +| `ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `source_lines_error_library_frames` | `5` | +| `ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES` | `source_lines_span_app_frames` | `0` | +| `ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES` | `source_lines_span_library_frames` | `0` | + +By default, the APM agent collects source code snippets for errors. +Use the above settings to modify how many lines of source code are collected. + +We differ between errors and spans, as well as library frames and app frames. + + +Especially for spans, collecting source code can have a large impact on +storage use in your Elasticsearch cluster. + + +
+ +### `span_frames_min_duration` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `span_frames_min_duration` | `"5ms"` | + +Use this to disable stack trace frame collection for spans with a duration shorter +than or equal to the given amount of milleseconds. + +The default is `"5ms"`. + +Set it to `-1` to collect stack traces for all spans. +Set it to `0` to disable stack trace collection for all spans. + +It has to be provided in **duration format**. + +
+ +### `server_ca_cert_file` + +| Environment | `Config` key | Default | Example | +|---|---|---|---| +| `ELASTIC_APM_SERVER_CA_CERT_FILE` | `server_ca_cert_file` | `nil` | `'/path/to/ca.pem'` | + +The path to a custom CA certificate for connecting to APM Server. + +
+ +### `stack_trace_limit` + +| Environment | `Config` key | Default | +|---|---|---| +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `stack_trace_limit` | `999999` | + +The maximum number of stack trace lines per span/error. + +
+ +### `transaction_max_spans` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `transaction_max_spans` | `500` | + +Limits the amount of spans that are recorded per transaction. +This is helpful in cases where a transaction creates a very high amount of spans +(e.g. thousands of SQL queries). +Setting an upper limit will prevent overloading the agent and the APM server with +too much work for such edge cases. + +
+ +### `transaction_sample_rate` + +Dynamic + +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `transaction_sample_rate` | `1.0` | + +By default, the agent will sample every transaction (e.g. request to your service). +To reduce overhead and storage requirements, you can set the sample rate to a value +between `0.0` and `1.0`. +We still record overall time and the result for unsampled transactions, but no +context information, tags, or spans. +The sample rate will be rounded to 4 digits of precision. + +
+ +### `verify_server_cert` +| | | | +|---|---|---| +| Environment | `Config` key | Default | +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `verify_server_cert` | `true` | + +By default, the agent verifies the SSL certificate if you use an HTTPS connection to +the APM server. +Verification can be disabled by changing this setting to `false`. + +
+ +## Configuration formats + +Some options require a unit, either duration or size. +These need to be provided in a specific format. + +
+ +### Duration format + +The _duration_ format is used for options like timeouts. +The unit is provided as suffix directly after the number, without any separation by whitespace. + +**Example**: `"5ms"` + +**Supported units** + + * `ms` (milliseconds) + * `s` (seconds) + * `m` (minutes) + +
+ +### Size format + +The _size_ format is used for options like maximum buffer sizes. +The unit is provided as suffix directly after the number, without any separation by whitespace. + +**Example**: `10kb` + +**Supported units**: + + * `b` (bytes) + * `kb` (kilobytes) + * `mb` (megabytes) + * `gb` (gigabytes) + + +We use the power-of-two sizing convention, e.g. `1 kilobyte == 1024 bytes`. + + +
+ +## Special configuration + +Elastic APM patches `Kernel#require` to auto-detect and instrument supported third-party libraries. It does so with the utmost care but in rare cases, it can conflict with some libraries. + +To get around this patch, set the environment variable `ELASTIC_APM_SKIP_REQUIRE_PATCH` to `"1"`. + +The agent might need some additional tweaking to make sure the third-party libraries are picked up and instrumented. Make sure you require the agent _after_ you require your other dependencies. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx index fa3e2268a8..594e3594cb 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx @@ -5,3 +5,102 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at +[elastic.co](https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html) + + + +
+ +Add the gem to your `Gemfile`: + +```ruby +gem 'elastic-apm' +``` + +Create a file `config/elastic_apm.yml`: + +```yaml +server_url: http://localhost:8200 +secret_token: '' +``` + +Include the middleware, start (and stop) Elastic APM when booting your app: + +```ruby +# config.ru + +app = lambda do |env| + [200, {'Content-Type' => 'text/plain'}, ['ok']] +end + +# Wraps all requests in transactions and reports exceptions +use ElasticAPM::Middleware + +# Start an instance of the Agent +ElasticAPM.start(service_name: 'NothingButRack') + +run app + +# Gracefully stop the agent when process exits. +# Makes sure any pending transactions are sent. +at_exit { ElasticAPM.stop } +``` + +
+ +## Sinatra example + +```ruby +# Example config.ru + +require 'sinatra/base' + +class MySinatraApp < Sinatra::Base + use ElasticAPM::Middleware + + # ... +end + +# Takes optional ElasticAPM::Config values +ElasticAPM.start(app: MySinatraApp, ...) + +# You can also do the following, which is equivalent to the above: +# ElasticAPM::Sinatra.start(MySinatraApp, ...) + +run MySinatraApp + +at_exit { ElasticAPM.stop } +``` + +
+ +## Grape example + +```ruby +# Example config.ru + +require 'grape' + +module Twitter + class API < Grape::API + use ElasticAPM::Middleware + + # ... + end +end + +# Start the agent and hook in your app +ElasticAPM::Grape.start(Twitter::API, config) + +run Twitter::API + +``` diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx index 66a887e6fa..d47eac484e 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx index 30576f574b..271d8e8c11 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx @@ -5,3 +5,111 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +Using any APM solution comes with trade-offs, and the Elastic APM Ruby Agent is no different. +Instrumenting your code, using timers, recording context data, etc., uses resources—for example: + +* CPU time +* Memory +* Bandwidth +* Elasticsearch storage + +We invest a lot of effort to ensure that the Ruby Agent is suitable for production code +and that its overhead remains as low as possible. +However, because every application is different, there are some knobs you can turn and tweak to adapt the Agent to your specific needs. + +
+ +## Transaction sample rate + +By default, the Agent samples every transaction. +The easiest way to reduce both the overhead of the agent and storage requirements, +is to tell it to do less, i.e., sample fewer transactions. +To do this, set the `transaction_sample_rate` +to a value between `0.0` and `1.0`—the percentage of transactions you'd like to randomly sample. +The Agent will still record the overall time and result of unsampled transactions, +but not context information, tags, or spans. + +
+ +## Collecting frame context + +The Agent automatically captures several lines of source code around each frame location in the stack trace. +This enables the APM app to provide greater insight into exactly where an error or span is occurring in your code. +This insight does come at a cost—in terms of performance, stack trace collection is the most expensive thing the Agent does. + +There are settings you can modify to control this behavior: + +1. Disable stack trace frame collection for short-duration spans by setting + `span_frames_min_duration` to `0`. + +1. Modify the number of source code lines collected. + These settings are divided between app frames, which represent your application code, + and library frames, which represent the code of your dependencies. + Each of these categories are further split into separate error and span settings. + + * `source_lines_error_app_frames` + * `source_lines_error_library_frames` + * `source_lines_span_app_frames` + * `source_lines_span_library_frames` + +1. If you're using the API to create a custom span, you can disable stack trace collection with the + `include_stacktrace` argument. + +Reading source files inside a running application can cause a lot of disk I/O, +and sending up source lines for each frame will have a network and storage cost that is quite high. +Turning these limits down will prevent storing excessive amounts of data in Elasticsearch. + +
+ +## Transaction queue + +The Agent does not send every transaction as it happens. +Instead, to reduce load on the APM Server, the Agent uses a queue. +The queue is flushed periodically, or when it reaches a maximum size. + +While this reduces the load on the APM Server, holding on to transaction data in a queue uses memory. +If you notice a large increase in memory use, try adjusting these settings: + + * `api_request_time` to reduce the duration of a single streaming request. + This setting is helpful if you have a sustained high number of transactions. + + * `api_request_size` to reduce the maximum size of one request. + This setting can help if you experience transaction peaks (a large number in a short period of time). + +Keep in mind that reducing the value of either setting will cause the agent to send more HTTP requests to the APM Server, +potentially causing a higher load. + +
+ +## Spans per transaction + +The number of spans per transaction will influence both how much time the agent spends in each transaction collecting contextual data, +and how much storage space is needed in Elasticsearch. +In our experience, most _usual_ transactions should have well below 100 spans. +In some cases, however, the number of spans can explode—for example: + +* Long-running transactions +* Unoptimized code, e.g., doing hundreds of SQL queries in a loop + +To avoid these edge cases which overload both the Agent and the APM Server, +the Agent will stop recording spans when a specified limit is reached. +This limit is configurable with `transaction_max_spans`. + +
+ +## Capturing headers and request body + +You can configure the Agent to capture headers and request bodies with +`capture_headers` and {/* `capture_body` */}. +By default, headers are captured and request bodies are not. + +Depending on the nature of your POST requests, capturing request bodies for transactions may introduce noticeable overhead, +as well as increased storage use. +In most scenarios, we advise against enabling request body capturing for transactions, and only enabling it if necessary for errors. + +Capturing request/response headers has less overhead on the agent than capturing request bodies, +but can have an impact on storage use. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx index a76daf1bde..d8fa71aa73 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx @@ -5,3 +5,162 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at [elastic.co](https://www.elastic.co/guide/en/apm/agent/ruby) + + + +
+ +The Elastic APM Ruby Agent has built-in support for many frameworks and +libraries. Generally, we want to support all of the most popular libraries. If your favorite +is missing, feel free to request it in an issue, or better yet, create a pull +request. + +
+ +## Ruby + +We follow Ruby's own maintenance policy and officially support all currently +maintained versions per +[Ruby Maintenance Branches](https://www.ruby-lang.org/en/downloads/branches/). + +
+ +## Web Frameworks and Libraries + +We have automatic support for Ruby on Rails and all Rack compatible web +frameworks. + +We test against all supported minor versions of Rails, Sinatra, and Grape. + +
+ +### Ruby on Rails + +We currently support all versions of Rails since 4.2. +This follows Rails' own [Security policy](https://rubyonrails.org/security/). + +See {/* Getting started with Rails */}. + +
+ +### Sinatra + +We currently support all versions of Sinatra since 1.0. + +See {/* Getting started with Rack */}. + +
+ +### Grape + +We currently support all versions of Grape since 1.2. + +See {/* Grape example */}. + +
+ +## Databases + +We automatically instrument database actions using: + +- ActiveRecord (v4.2+) +- DynamoDB (v1.0+) +- Elasticsearch (v0.9+) +- Mongo (v2.1+) +- Redis (v3.1+) +- Sequel (v4.35+) + +
+ +## External HTTP requests + +We automatically instrument and add support for distributed tracing to external +requests using these libraries: + +- `net/http` +- Http.rb (v0.6+) +- Faraday (v0.2.1+) + +**Note:** These libraries usually assume `localhost` if no `Host` is specified, so the agent does as well. + +
+ +## Background Processing + +We automatically instrument background processing using: + +- DelayedJob +- Sidekiq +- Shoryuken +- Sneakers (v2.12.0+) (Experimental, see [#676](https://github.com/elastic/apm-agent-ruby/pull/676)) +- Resque (v2.0.0+) +- SuckerPunch (v2.0.0+) + +
+ +## Resque + +To make the agent work with Resque, you need to require `elastic_apm/resque` before you boot your Resque worker process. + +For example in your `Rakefile`: + +```ruby +require 'resque' +require 'elastic_apm' +require 'elastic_apm/resque' +``` + +When you start Resque, you should see a series of messages like the following in the Resque logs: + +```ruby +I, [XXX #81227] INFO -- : Starting worker main +D, [XXX #81227] DEBUG -- : Registered signals +I, [XXX #81227] INFO -- : Running before_first_fork hooks +D, [XXX #81227] DEBUG -- : Starting ElasticAPM agent +``` + +Also be sure to set the Resque environment variable `RUN_AT_EXIT_HOOKS` to `true`. Otherwise, the fork may be +terminated before the agent has a chance to send all the fork's events to the APM server. + +
+ +## SuckerPunch + +Asynchronously executed jobs in SuckerPunch are automatically instrumented. + +Note that errors raised in the user-defined `JobClass#perform` method will be first handled by the SuckerPunch exception +handler before being handled by the agent. The handler is accessed/set via `SuckerPunch.exception_handler` in version +2.0. The agent transaction will be marked as successful unless you re-raise the error in the exception handler. +You can also explicitly report the error via `ElasticAPM.report` in a custom SuckerPunch exception +handler. + +
+ +## gRPC + +We automatically instrument gRPC using the `grpc` gem. Note that this is experimental, as the `grpc` gem's +support for `Interceptors` is experimental as of version 1.27.0. + +To instrument a client, add the `ElasticAPM::GRPC::ClientInterceptor` as an `interceptor` at Stub creation. + +```ruby +Helloworld::Greeter::Stub.new( + 'localhost:50051', + interceptors: [ElasticAPM::GRPC::ClientInterceptor.new] +) +``` + +To instrument a server, add the `ElasticAPM::GRPC::ServerInterceptor`. + +```ruby +GRPC::RpcServer.new(interceptors: [ElasticAPM::GRPC::ServerInterceptor.new]) +``` diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx index 36f0f944c0..74b3e5d4b6 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx @@ -5,3 +5,45 @@ title: Ruby # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + + +export let env_github = false + + + +For the best reading experience, +please view this documentation at +[elastic.co](https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html) + + + +
+ +The Elastic APM Ruby Agent sends performance metrics and error logs to the APM Server. +It has built-in support for {/* Ruby on Rails */} and other +{/* Rack-compatible */} applications. +It also offers an API which allows you to instrument any application. + +
+ +## How does the Agent work? + +The agent auto-instruments supported technologies and records interesting events, +like HTTP requests and database queries. To do this, it uses relevant public APIs when they are provided by the libraries. Otherwise, it carefully wraps the necessary internal methods. +This means that for the supported technologies, there are no code changes required. + +The Agent automatically keeps track of queries to your data stores to measure their duration and metadata (like the DB statement), +as well as HTTP related information (like the URL, parameters, and headers). + +These events, called Transactions and Spans, are sent to the APM Server. +The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + +
+ +## Additional Components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx index bb31c84e6a..7c6abdadb1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx @@ -5,3 +5,290 @@ title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +You can access agent API after initializing the agent: + +```js +var apm = require('@elastic/apm-rum').init(...) +``` + +
+ +## `apm.init([config])` + +Initializes the agent with the given configuration and returns itself. Under the hood init does the following + +* Registers a global `error` listener to track JavaScript errors on the page. +* Adds a `onload` event listener to collect the page load metrics. + + +When the agent is inactive, both `error` and `onload` listeners will not be registered on the page + + + +Both XHR and Fetch API are patched as soon as the agent script is executed on the page and does not get changed even if the agent is inactive. The reason is to allow users to initialize the agent asynchronously on the page. + + +
+ +## `apm.setUserContext()` + +```js +apm.setUserContext(context) +``` + +Call this method to enrich collected performance data and errors with information about the user. + +The given `context` argument must be an object and can contain the following properties (all optional): + +* `id` - The users ID +* `username` - The users username +* `email` - The users e-mail + +The provided user context is stored under `context.user` in Elasticsearch on both errors and transactions. + +It’s possible to call this function multiple times within the scope of the same active transaction. +For each call, the properties of the context argument are shallow merged with the context previously given. + +
+ +## `apm.setCustomContext()` + +```js +apm.setCustomContext(context) +``` + +Call this to enrich collected errors and transactions with any information that you think will help you debug performance issues or errors. + +The provided custom context is stored under `context.custom` in Elasticsearch on both errors and transactions. + +It’s possible to call this function multiple times within the scope of the same active transaction. +For each call, the properties of the context argument are shallow merged with the context previously given. + +The given `context` argument must be an object and can contain any property that can be JSON encoded. + + +Before using custom context, ensure you understand the different types of +[metadata](((apm-guide-ref))/metadata.html) that are available. + + +
+ +## `apm.addLabels()` + +```js +apm.addLabels({ [name]: value }) +``` + +Set labels on transactions and errors. +Starting with APM Server 7.6+, the labels are added to spans as well. + +Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via {/* `apm.setCustomContext()` */}). You can set multiple labels. + + +Before using custom labels, ensure you understand the different types of +[metadata](((apm-guide-ref))/metadata.html) that are available. + + +Arguments: + +* `name` - Any string. All periods (.), asterisks (*), and double quotation marks (") will be replaced by underscores (_), as those characters have special meaning in Elasticsearch + +* `value` - Any string, boolean, or number. All other data types will be converted to a string + before being sent to the APM Server. + + +Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +[mapping explosion](((ref))/mapping.html#mapping-limit-settings). + + +
+ +## `apm.addFilter()` + +A filter can be used to modify the APM payload before it is sent to the apm-server. +This can be useful in for example redacting sensitive information from the payload: + +```js +apm.addFilter(function (payload) { + if (payload.errors) { + payload.errors.forEach(function (error) { + error.exception.message = error.exception.message.replace('secret', '[REDACTED]') + }) + } + if (payload.transactions) { + payload.transactions.forEach(function (tr) { + tr.spans.forEach(function (span) { + if (span.context && span.context.http && span.context.http.url) { + var url = new URL(span.context.http.url) + if (url.searchParams.get('token')) { + url.searchParams.set('token', 'REDACTED') + } + span.context.http.url = url.toString() + } + }) + }) + } + // Make sure to return the payload + return payload +}) +``` + + +The payload will be dropped if one of the filters return a falsy value. + + +
+ +## `apm.startTransaction()` + +```js +const transaction = apm.startTransaction(name, type, options) +``` + +Starts and returns a new transaction. + +Arguments: + +* `name` - The name of the transaction (string). Defaults to `Unknown` + +* `type` - The type of the transaction (string). Defaults to `custom` + +* `options` - Options to modify the created transaction (object). + This argument is optional. The following options are supported: + + * `managed` - Controls whether the transaction is managed by the agent or not. Defaults to `false`. + +Use this method to create a custom transaction. + +By default, custom transactions are not managed by the agent, however, you can start a managed transaction + by passing `{ managed: true }` as the `options` argument. + +There are some differences between managed and unmanaged transactions: + +* For managed transactions, the agent keeps track of the relevant tasks during the lifetime of the transaction + and automatically ends it once all of the tasks are finished. Unmanaged transactions need to be ended + manually by calling the {/* `end` */} method. + +* Managed transactions include information captured via our auto-instrumentations (e.g. XHR spans). + See Supported Technologies for a list of instrumentations. + +* There can only be one managed transaction at any given time -- + starting a second managed transaction will end the previous one. + There are no limits for unmanaged transactions. + + +This method returns `undefined` if apm is disabled or if active flag is set to `false` in the config. + + +
+ +## `apm.startSpan()` + +```js +const span = apm.startSpan(name, type, options) +``` + +Starts and returns a new span associated with the current active transaction. + +Arguments: + +* `name` - The name of the span (string). Defaults to `Unknown` + +* `type` - The type of the span (string). Defaults to `custom` + +* `options` - The following options are supported: + + * `blocking` - Blocks the associated transaction from ending until this span is ended. Blocked spans + automatically create an internal task. Defaults to false. + + * `parentId` - Parent id associated with the new span. Defaults to current transaction id + + * `sync` - Denotes if the span is synchronous or asynchronous. Defaults to null + +Blocked spans allow users to control the early closing of {/* managed transactions */} in few cases when the app contains lots of async activity which cannot be tracked by the agent. + + +This method returns `undefined` if apm is disabled or if active flag is set to `false` in the config. + + +
+ +## `apm.setInitialPageLoadName()` + +```js +apm.setInitialPageLoadName(name) +``` + +Arguments: + +* `name` - The name of the page-load transaction (string). + +Use this method to set the name of the `page-load` transaction that is sent automatically on page load event. +See the {/* custom initial page load transaction names */} documentation for more details. + +
+ +## `apm.getCurrentTransaction()` + +```js +apm.getCurrentTransaction() +``` + +Use this method to get the current active transaction. If there is no active transaction it will return `undefined`. + +
+ +## `apm.captureError()` + +```js +apm.captureError(error) +``` + +Arguments: + +* `error` - An instance of `Error`. + +Use this method to manually send an error to APM Server: + +```js +apm.captureError(new Error('')) +``` + +
+ +## `apm.observe()` + +```js +apm.observe(name, callback) +``` + +Arguments: + +* `name` - The name of the event. + +* `callback` - A callback function to execute once the event is fired. + +Use this method to listen for RUM agent internal events. + +The following events are supported for the transaction lifecycle: + +* `transaction:start` event is fired on every transaction start. +* `transaction:end` event is fired on transaciton end and before it is added to the queue to be sent to APM Server. + +The callback function for these events receives the corresponding transaction object + as its only argument. The transaction object can be modified through + methods and properties documented in {/* Transaction API */}: + +```js +apm.observe('transaction:start', function (transaction) { + if (transaction.type === 'custom') { + transaction.name = window.document.title + transaction.addLabels({ 'custom-label': 'custom-value' }) + } +}) +``` diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx index 173de43b62..b70e6dab14 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx @@ -5,3 +5,421 @@ title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +While initializing the agent you can provide the following configuration options: + +
+ +## `serviceName` + +* **Type:** String +* **Required** + +The Elastic APM service name is used to differentiate data from each of your services. +Can only contain alphanumeric characters, spaces, underscores, and dashes (must match ^[a-zA-Z0-9 _-]+$). + +
+ +## `serverUrl` + +* **Type:** String +* **Default:** `http://localhost:8200` + +The URL used to make requests to the APM Server. + +
+ +## `serverUrlPrefix` + +* **Type:** String +* **Default** `/intake/v${apiVersion}/rum/events` + +The server prefix URL used to make requests to the APM Server. Some ad blockers block outgoing requests +from the browser if the default server prefix URL is being used. Using a custom server prefix URL can be used to +evade the ad blocker. + + +If the default server prefix URL is overwritten, the reverse proxy that sits between the +APM Server and the rum agent must reroute traffic to `/intake/v${apiVersion}/rum/events` +so the APM Server knows what intake API to use. + + +
+ +## `serviceVersion` + +* **Type:** String + +The version of the app. +This could be the version from your `package.json` file, +a git commit reference, +or any other string that might help you reference a specific version. +This option is used on the APM Server to find the right sourcemap file to apply to the stack trace. + +
+ +## `active` + +* **Type:** Boolean +* **Default:** `true` + +A Boolean value that specifies if the agent should be active or not. +If active, the agent will send APM transactions and track errors. +This option can be used to deactivate the agent in your staging environment. +It can also be used to sample a number of clients. Below is an example to sample 10% of the page loads: + +```js +var options = { + active: Math.random() < 0.1 +} +``` + +
+ +## `instrument` + +* **Type:** Boolean +* **Default:** `true` + +A Boolean value that specifies if the agent should automatically instrument the application to collect +performance metrics for the application. + + +Both active and instrument needs to be true for instrumentation to be running. + + +
+ +## `disableInstrumentations` + +* **Type:** Array +* **Default:** `[]` + +A list of instrumentations which can be disabled. When disabled, no transactions or spans will be created for that type. +The valid options are: + +* `page-load` +* `history` +* `eventtarget` +* `click` +* `xmlhttprequest` +* `fetch` +* `error` + + +To disable all `http-request` transactions, add both `fetch` and `xmlhttprequest`. +to this config. + + + +To disable `user-interaction` transactions, add `eventtarget` or `click` to this config. +The option `eventtarget` is deprecated and will be removed in the future releases. + + +
+ +## `environment` + +* **Type:** String +* **Default:** `''` + +The environment where the service being monitored is deployed, e.g. "production", "development", "test", etc. + +Environments allow you to easily filter data on a global level in the APM app. +It's important to be consistent when naming environments across agents. +See [environment selector](((apm-app-ref))/filters.html#environment-selector) in the APM app for more information. + + +This feature is fully supported in the APM app in Kibana versions >= 7.2. +You must use the query bar to filter for a specific environment in versions prior to 7.2. + + +
+ +## `logLevel` + +* **Type:** String +* **Default:** `'warn'` + +Set the verbosity level for the agent. +This does not have any influence on the types of errors that are sent to the APM Server. This option is useful when you want to report an issue with the agent to us. + +Possible levels are: `trace`, `debug`, `info`, `warn`, and `error`. + +
+ +## `apiVersion` + +* **Type:** number +* **Default:** `2` + +This denotes the version of APM Server's intake API. Setting this value to any number +above `2` will compress the events (transactions and errors) payload sent to the server. + + +This feature requires APM Server >= 7.8. Setting this flag to number > 2 with older +APM server version would break the RUM payload from reaching the server. + + +
+ +## `breakdownMetrics` + +* **Type:** Boolean +* **Default:** `false` + +Enable or disable the tracking and collection of breakdown metrics for the transaction. + + +This feature requires APM Server and Kibana >= 7.4. Setting this flag to `true` with older APM server version +would break the RUM payload from reaching the server. + + + +Breakdown distribution for the transaction varies depending on the type of the transaction. +To understand the different types, see {/* Breakdown Metrics */} + + +
+ +## `flushInterval` + +* **Type:** Number +* **Default:** `500` + +The agent maintains a single queue to record transaction and error events when they are added. +This option sets the flush interval in **milliseconds** for the queue. + + +After each flush of the queue, the next flush isn't scheduled until an item is added to the queue. + + +
+ +## `pageLoadTraceId` + +* **Type:** String + +This option overrides the page load transactions trace ID. + +
+ +## `pageLoadSampled` + +* **Type:** Boolean + +This option overrides the page load transactions sampled property. +It is only applicable to `page-load` transactions. + +
+ +## `pageLoadSpanId` + +* **Type:** String + +This option overrides the ID of the span that is generated for receiving the initial document. + +
+ +## `pageLoadTransactionName` + +* **Type:** String + +This option sets the name for the page load transaction. By default, transaction names for hard (page load) and soft (route change) navigations are +inferred by the agent based on the current URL. Check the {/* custom initial page load transaction names */} +documentation for more details. + +
+ +## `distributedTracing` + +* **Type:** Boolean +* **Default:** `true` + +Distributed tracing is enabled by default. Use this option to disable it. + +
+ +## `distributedTracingOrigins` + +* **Type:** Array +* **Default:** `[]` + +This option can be set to an array containing one or more Strings or RegExp objects and determines which origins should be monitored as part of distributed tracing. +This option is consulted when the agent is about to add the distributed tracing HTTP header (`traceparent`) to a request. +Please note that each item in the array should be a valid URL containing the origin (other parts of the url are ignored) or a RegExp object. If an item in the array is a string, an exact match will be performed. If it's a RegExp object, its test function will be called with the request origin. + +```js +var options = { + distributedTracingOrigins: ['https://example.com', /https?:\/\/example\.com:\d{4}/] +} +``` + +
+ +## `propagateTracestate` + +* **Type:** Boolean +* **Default:** `false` + +When distributed tracing is enabled, this option can be used to propagate the [tracestate](https://www.w3.org/TR/trace-context/#tracestate-header) +HTTP header to the configured origins. Before enabling this flag, make sure to change your {/* server configuration */} to avoid +Cross-Origin Resource Sharing errors. + +
+ +## Event throttling + +Throttle the number of events sent to APM Server. + +
+ +### `eventsLimit` + +By default, the agent can only send up to `80` events every `60000` milliseconds (one minute). + +* **Type:** Number +* **Default:** `80` + +
+ +### `transactionSampleRate` + +* **Type:** Number +* **Default:** `1.0` + +A number between `0.0` and `1.0` that specifies the sample rate of transactions. By default, all transactions are sampled. + +
+ +### `centralConfig` + +* **Type:** Boolean +* **Default:** `false` + +This option activates APM Agent Configuration via Kibana. +When set to `true`, the agent starts fetching configurations via the APM Server during the initialization phase. +These central configurations are cached in `sessionStorage`, and will not be fetched again until +the session is closed and/or `sessionStorage` is cleared. +In most cases, this means when the tab/window of the page is closed. + + +Currently, only transaction sample rate can be configured via Kibana. + + + +This feature requires APM Server v7.5 or later. +More information is available in [APM Agent configuration](((apm-app-ref))/agent-configuration.html). + + +
+ +### `ignoreTransactions` + +* **Type:** Array +* **Default:** `[]` + +An array containing a list of transaction names that should be ignored when sending the payload to the APM server. +It can be set to an array containing one or more Strings or RegExp objects. If an element in the array is a String, an exact match will be performed. +If an element in the array is a RegExp object, its test function will be called with the name of the transation. + +```js +const options = { + ignoreTransactions: [/login*/, '/app'] +} +``` + + +Spans that are captured as part of the ignored transactions would also be ignored. + + +
+ +### `monitorLongtasks` + +* **Type:** Boolean +* **Default:** `true` + +Instructs the agent to start monitoring for browser tasks that block the UI +thread and might delay other user inputs by affecting the overall page +responsiveness. Learn more about {/* long task spans */} and how to interpret them. + +
+ +### `apmRequest` + +* **Type:** Function +* **Default:** `null` + +```js +apm.init({ apmRequest: (requestParams) => true}) +``` + +Arguments: + +* `requestParams` - This is an object that contains the APM HTTP request details: + + * `url` - The full url of the APM server + + * `method` - Method of the HTTP request + + * `headers` - Headers of the HTTP request + + * `payload` - Body of the HTTP request + + * `xhr` - The `XMLHttpRequest` instance used by the agent to send the request + +`apmRequest` can be used to change or reject requests that are made to the +APM Server. This config can be set to a function, which is called whenever the agent +needs to make a request to the APM Server. + +The callback function is called with a single argument and is expected to return +an output synchronously. If the return value is `true` then the agent continues +with making the (potentially modified) request to the APM Server. + +If this function returns a falsy value the request is discarded with a warning in the console. + +The following example adds a header to the HTTP request: + +```js +apm.init({ + apmRequest({ xhr }) { + xhr.setRequestHeader('custom', 'header') + return true + } +}) +``` + +This example instructs the agent to discard the request, since it's handled by the user: + +```js +apm.init({ + apmRequest({ url, method, headers, payload }) { + // Handle the APM request here or at some later point. + fetch(url, { + method, + headers, + body: payload + }); + return false + } +}) +``` + +
+ +### `sendCredentials` + +* **Type:** Boolean +* **Default:** `false` + +This allows the agent to send cookies when making requests to the APM server. +This is useful on scenarios where the APM server is behind a reverse proxy that requires requests to be authenticated. + + +If APM Server is deployed in an origin different than the page’s origin, you will need to +{/* configure Cross-Origin Resource Sharing (CORS) */}. + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx index eda18e85da..c12a8b1071 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx @@ -5,3 +5,49 @@ title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +If APM Server is deployed in an origin different than the page's origin, +you will need to configure Cross-Origin Resource Sharing (CORS). + +A list of permitted origins can be supplied to the +[`apm-server.rum.allow_origins`](((apm-guide-ref))/configuration-rum.html#rum-allow-origins) +configuration option. +By default, APM Server allows all origins. + +## How CORS works + +When the RUM agent makes its initial `POST` request, the browser will check to see if it is a cross-origin request. +If it is, the browser automatically makes a preflight `OPTIONS` request to the server to ensure the original `POST` request is allowed. +If this `OPTIONS` check passes, then the original `POST` request is allowed. +This request will fail if RUM support is not configured in the APM Server. + +If you use a proxy, the preflight request headers may be necessary for your configuration: + +```js +Access-Control-Request-Headers: Content-Type +Access-Control-Request-Method: POST +Origin: [request-origin] +``` + +The response should include these headers: + +```js +Access-Control-Allow-Headers: Content-Type +Access-Control-Allow-Methods: POST, OPTIONS +Access-Control-Allow-Origin: [request-origin] +``` + +If you enable the `sendCredentials` configuration option, your proxy's response must include the header `Access-Control-Allow-Origin` with the page's origin as a value, and the following header: + +```js +Access-Control-Allow-Credentials: true +``` + + +To learn more about CORS, see the MDN page on +[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). + + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx index 9cd1c89d49..8bcdd10679 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx @@ -5,3 +5,5 @@ title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + +No source content found. diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx index 3b99ddf95a..3adfe5b653 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx @@ -5,3 +5,63 @@ title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +There are different ways to optimize/tune the performance of the RUM agent. +Which options to adjust depends on whether you are optimizing for speed, memory +usage, bandwidth or storage. + +
+ +## Sampling + +The first knob to reach for when tuning the performance of the agent is `transactionSampleRate`. +Adjusting the sampling rate controls what ratio of requests are traced. +By default, the sample rate is set at `1.0`, meaning _all_ requests are traced +and sent to the APM server. + +The sample rate will impact all four performance categories, +so simply turning down the sample rate is an easy way to improve performance. + +Here's an example of setting the sample rate to 20%: + +```js +import { apm } from "@elastic/apm-rum" + +apm.init({ + transactionSampleRate: 0.2 +}) +``` + +The Agent will still record the overall duration and result of unsampled +transactions, but will discard associated spans, context information or labels +before sending to the APM server. + +
+ +## Breakdown Metrics + +Breakdown metrics help visualize where your application is spending the majority of +its time. The `breakdownMetrics` config controls whether metrics +should be calculated for each transaction based on its corresponding type. + +Setting this to `true` will increase the payload/bandwidth usage data to +the APM server. + +
+ +## APM Agent Configuration + +Activate agent configuration via Kibana to start fetching new configuration +changes from the APM server during the agent initialization phase. + +Setting the config option `centralConfig` to `true` +incurs the cost of one additional HTTP request when the agent is +initialized and generates more load to the APM server. As a result, +central configuration is disabled by default in RUM agent. + +It is recommended to disable this configuration when the instrumented +application is under heavy load. + diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx index f18bcb1212..7e657a6f12 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx @@ -5,3 +5,137 @@ title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +
+ +## Page load metrics + +The RUM agent tries to capture the overall user experience on how the page is loaded/rendered as part of the page load Transaction. +It includes all of the dependent resources, like JavaScript, stylesheets, images, etc., which are included as part of the page. In addition +to capturing the resource timing information as Spans, the transaction also includes navigation spans—marks that are associated with the rest +of the captured information to make the waterfall more appealing. + +`Domain lookup` + : Duration of the DNS query for the current page: `domainLookupEnd` - `domainLookupStart`. + +`Making a connection to the server` + : Duration of the TCP connection to the server, including the TLS negotiation time for HTTPS pages: `connectEnd` - `connectStart`. + +`Requesting and receiving the document` + : Overall response time of the server including the last byte: `responseEnd` - `requestStart`. + +`Parsing the document, executing sync. scripts` + : HTML document parsing time, including synchronous Stylesheets and Script: `tagsdomInteractive` - `domLoading`. + +`Fire "DOMContentLoaded" event` + : Triggered when the browser completes parsing the document. Helpful when there are multiple listeners, or logic + is executed: `domContentLoadedEventEnd` - `domContentLoadedEventStart`. + +`Fire "load" event` + : Trigged when the browser finishes loading its document and dependent resources: `loadEventEnd` - `loadEventStart`. + +`Time to first byte (TTFB)` + : Duration from the browser making an HTTP request for the initial document to the first byte of the page being received. TTFB is available from the Navigation Timing API as the `reponseStart` timestamp, and captured as transaction mark `transaction.marks.agent.timeToFirstByte` in the ElasticSearch document. + +To capture the overall user experience of the page including all of the above information plus additional resource requests that might be +triggered during the execution of dependent resources, the `page-load` transaction duration might not always reflect the +[Load](https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event) event of the browser and can extend beyond the event. + +If you are interested in accurately measuring the duration of load event, the information can be extracted by using +`Fire load event` Span or from the Transaction marks available as `transaction.marks.agent.domComplete` in the Elasticsearch document. + + +The page load transaction is measured relative to the `fetchStart` timestamp from the Navigation Timing API. + + +
+ +## User-centric Metrics + +To understand the performance characteristics of a web page beyond the page load and how the user perceives performance, the agent supports capturing these [responsiveness metrics](https://web.dev/user-centric-performance-metrics/). + +`First contentful paint (FCP)` + : Focusses on the initial rendering and measures the time from when the page starts loading to when any part of the page's content is displayed on the screen. The agent uses the [Paint timing API](https://www.w3.org/TR/paint-timing/#first-contentful-paint) available in the browser to capture the timing information. FCP is captured as transaction mark for `page-load` transaction for all chromium-based browsers (Chrome >60, Edge >79, Opera >47, etc.). + +`Largest contentful paint (LCP)` + : A new page-load metric that denotes the time from when the page starts loading to when the critical element (largest text, image, video elements) is displayed on the screen. LCP is available in the browser through + [LargestContentfulPaint API](https://wicg.github.io/largest-contentful-paint/) which relies on the draft [Element Timing API](https://wicg.github.io/element-timing/). LCP is one of the [core web vitals](https://web.dev/vitals/) metrics and + available only in Chrome >77. Captured as transaction mark for `page-load` transaction, maintain LCP within the first **2.5 seconds** of page-load to provide a good user experience. + +`First input delay (FID)` + : FID quantifies the experience of the user when they interact with the page during the page load. It is measured as the time between when a user first interacts with your site (mouse clicks, taps, select dropdowns, etc.) to the time when the + browser can respond to that interaction. FID is one of the [core web vitals](https://web.dev/vitals/) metrics and available only in Chrome >85 via [Event Timing API](https://wicg.github.io/event-timing/). FID is captured as `First Input Delay` span for `page-load` transaction. Maintain FID **below 100 milliseconds** to provide a good user experience. + +`Total blocking time (TBT)` + : The sum of the blocking time (duration above 50 ms) for each long task that occurs between the First contentful paint and the time when the transaction is completed. [Total blocking time](https://web.dev/tbt/) is a + great companion metric for [Time to interactive](https://web.dev/tti/) (TTI) which is lab metric and not available in the field through browser APIs. The agent captures TBT based on the number of long tasks that occurred during the page load lifecycle. Captured as `Total Blocking Time` span for `page-load` transaction. + +`Cumulative layout shift (CLS)` + : Metric that represents the cumulative score of all unexpected layout shifts that occur during the entire lifespan of the page. CLS is one of the [core web vitals](https://web.dev/vitals/) metrics and here is + [how the score is calculated by Chrome](https://web.dev/cls/#layout-shift-score). Maintain a score of **less than 0.1** to provide a good user experience. + +`Long Tasks` + : A long task is any user activity or browser task that monopolize the UI thread for extended periods (greater than 50 milliseconds) and block other critical tasks (frame rate or input latency) + from being executed. The agent uses the [Long Task API](https://www.w3.org/TR/longtasks/) which is only available in chromium-based browsers (Chrome >58, Edge >79, Opera >69). Captured as `Longtask` span for all managed transactions. + Learn more about {/* long task spans */}, and how to interpret them. + +`User Timing` + : The [User Timing](https://www.w3.org/TR/user-timing/) spec exposes API for developers to add custom performance entries to their web application. These custom metrics allow users to measure the hot paths of the app code that helps to identify a good user experience. RUM agent records all of the [performance.measure](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceMeasure) calls as spans by their measure name in the waterfall for all managed transactions. + +
+ +## User Interactions + +The RUM agent automatically instruments click event listeners that are +registered by the application. The click events are captured as `user-interaction` +transactions. However, to avoid sending too many `user-interaction` transactions +to the server, the agent discards transactions with no spans (e.g. no network activity). Furthermore, +if the click interaction results in route change, then a `route-change` +transaction would be captured instead. + +The transaction name can be influenced either by using the `name` or preferably the `data-transaction-name` HTML attribute. +Examples of transaction names based on the html attributes present: + +* ``: `Click - button` + +* ``: `Click - button["purchase"]` + +* ``: `Click - purchase` + +
+ +## Single Page Applications + +All history `pushState` events will be captured as transactions. +Most of these transactions can be enhanced by using framework specific integrations. +For all unsupported frameworks/libraries, you can instrument the application +by creating {/* custom transactions and custom spans with the span API */}. + +
+ +## Frameworks + +The agent supports {/* integrations with certain frameworks */}. + +To instrument custom metrics, like rendering time or mounting time of components on frameworks like React, Angular, Vue, +etc., use the {/* custom transactions API */}. + +The core RUM agent supports websites based on multi-page (MPA) and single-page architectures (SPA). The core RUM agent can be used on its own with SPA sites, but we recommend using our framework-specific integrations for the following reasons: + +* **Pages are better grouped by routes**: This results in the `transaction.name` field mapping to the actual application route path declared in the SPA application. +* **Exact SPA navigation rendering**: Integration packages hook into the component lifecycle and measure the duration of the SPA transaction correctly. The core RUM agent is unable to determine when an SPA navigation is rendered and instead waits for the last network request before considering the SPA transition is finished. +* **Improved error capturing**: For example, when an error is thrown inside an Angular application, the framework integration will automatically capture it. The core RUM agent, however, is unable to capture the error as the default error handler doesn’t rethrow the error as a browser event. + +
+ +## Platforms + +The following platforms are supported: + +{/* Update this image by modifying this URL: */} +{/* https://badges.herokuapp.com/browsers?android=5.1&firefox=52&googlechrome=49,74&iexplore=11&iphone=12µsoftedge=17&safari=9 */} +{/* Additional information: https://github.com/exogen/badge-matrix */} +{/* ![Elastic APM RUM Agent compatibility](images/supported-technologies/-compatibility.png) */} diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx index 0f5ffabe14..9b283ead31 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx @@ -5,3 +5,42 @@ title: RUM # description: Description to be written tags: [ 'serverless', 'observability', '' ] --- + + +
+ +The Elastic APM Real User Monitoring (RUM) JavaScript Agent provides detailed performance metrics and error tracking of your web applications. +It has built-in support for popular platforms and frameworks, and an API for custom instrumentation. + +The Agent also supports {/* distributed tracing */} for all outgoing requests. +This enables you to analyze performance throughout your microservice architecture -- all in one view. + +
+ +## Features + +The agent uses browser timing APIs such as [Navigation Timing](https://w3c.github.io/navigation-timing/) +[Resource Timing](https://w3c.github.io/resource-timing/), [Paint Timing](https://w3c.github.io/paint-timing/), [User Timing](https://w3c.github.io/user-timing/), etc., and +captures the following information: + +* Page load metrics +* Load time of Static Assets (JS, CSS, images, fonts, etc.) +* API requests (XMLHttpRequest and Fetch) +* Single page application navigations +* User interactions (click events that trigger network activity) +* User-centric metrics (Long tasks, FCP, LCP, FID, etc.) +* Page information (URLs visited and referrer) +* Network connection information +* JavaScript errors +* {/* Distributed tracing */} +* {/* Breakdown metrics */} + +
+ +## Additional Components + +APM Agents work in conjunction with the [APM Server](((apm-guide-ref))/index.html), [Elasticsearch](((ref))/index.html), and [Kibana](((kibana-ref))/index.html). +The [APM Guide](((apm-guide-ref))/index.html) provides details on how these components work together, +and provides a matrix outlining [Agent and Server compatibility](((apm-guide-ref))/agent-server-compatibility.html). + +{/* The include that was here is another page */} diff --git a/serverless-observability.docnav.json b/serverless-observability.docnav.json index 5b5a0d2fbf..fef14369db 100644 --- a/serverless-observability.docnav.json +++ b/serverless-observability.docnav.json @@ -72,231 +72,408 @@ }, { "id": "serverlessObservabilityApmAgentsAndroid", + "classic-sources": [ "enApmAgentAndroidIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsAndroidGetStarted" + "id": "serverlessObservabilityApmAgentsAndroidGetStarted", + "classic-sources": [ "enApmAgentAndroidSetup" ] }, { - "id": "serverlessObservabilityApmAgentsAndroidSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsAndroidSupportedTechnologies", + "classic-sources": [ "enApmAgentAndroidSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsAndroidInstall" + "id": "serverlessObservabilityApmAgentsAndroidInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsAndroidConfigure" + "id": "serverlessObservabilityApmAgentsAndroidConfigure", + "classic-sources": [ "enApmAgentAndroidConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsAndroidApi" + "id": "serverlessObservabilityApmAgentsAndroidApi", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsAndroidPerformanceTuning" + "id": "serverlessObservabilityApmAgentsAndroidPerformanceTuning", + "classic-sources": [] } ] }, { "id": "serverlessObservabilityApmAgentsGo", + "classic-sources": [ "enApmAgentGoIntroduction" ], "items": [ { - "id": "serverlessObservabilityApmAgentsGoGetStarted" + "id": "serverlessObservabilityApmAgentsGoGetStarted", + "classic-sources": [ "enApmAgentGoGettingStarted" ] }, { - "id": "serverlessObservabilityApmAgentsGoSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsGoSupportedTechnologies", + "classic-sources": [ "enApmAgentGoSupportedTech" ] }, { - "id": "serverlessObservabilityApmAgentsGoInstall" + "id": "serverlessObservabilityApmAgentsGoInstall", + "classic-sources": [ "" ] }, { - "id": "serverlessObservabilityApmAgentsGoConfigure" + "id": "serverlessObservabilityApmAgentsGoConfigure", + "classic-sources": [ "enApmAgentGoConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsGoApi" + "id": "serverlessObservabilityApmAgentsGoApi", + "classic-sources": [ "enApmAgentGoApi" ] }, { - "id": "serverlessObservabilityApmAgentsGoPerformanceTuning" + "id": "serverlessObservabilityApmAgentsGoPerformanceTuning", + "classic-sources": [] } ] }, { "id": "serverlessObservabilityApmAgentsIos", + "classic-sources": [ "enApmAgentSwiftIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsIosGetStarted" + "id": "serverlessObservabilityApmAgentsIosGetStarted", + "classic-sources": [ "enApmAgentSwiftSetup" ] }, { - "id": "serverlessObservabilityApmAgentsIosSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsIosSupportedTechnologies", + "classic-sources": [ "enApmAgentSwiftSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsIosInstall" + "id": "serverlessObservabilityApmAgentsIosInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsIosConfigure" + "id": "serverlessObservabilityApmAgentsIosConfigure", + "classic-sources": [ "enApmAgentSwiftConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsIosApi" + "id": "serverlessObservabilityApmAgentsIosApi", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsIosPerformanceTuning" + "id": "serverlessObservabilityApmAgentsIosPerformanceTuning", + "classic-sources": [] } ] }, { "id": "serverlessObservabilityApmAgentsJava", + "classic-sources": [ "enApmAgentJavaIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsJavaGetStarted" - }, - { - "id": "serverlessObservabilityApmAgentsJavaSupportedTechnologies" - }, - { - "id": "serverlessObservabilityApmAgentsJavaInstall" - }, - { - "id": "serverlessObservabilityApmAgentsJavaConfigure" - }, - { - "id": "serverlessObservabilityApmAgentsJavaApi" - }, - { - "id": "serverlessObservabilityApmAgentsJavaPerformanceTuning" + "id": "serverlessObservabilityApmAgentsJavaGetStarted", + "classic-sources": [ + "enApmAgentJavaSetup", + "enApmAgentJavaSetupJavaagent", + "enApmAgentJavaSetupAttachCli", + "enApmAgentJavaSetupAttachApi", + "enApmAgentJavaSslConfiguration", + "enApmAgentJavaAwsLambda" + ] + }, + { + "id": "serverlessObservabilityApmAgentsJavaSupportedTechnologies", + "classic-sources": [ "enApmAgentJavaSupportedTechnologiesDetails" ] + }, + { + "id": "serverlessObservabilityApmAgentsJavaInstall", + "classic-sources": [] + }, + { + "id": "serverlessObservabilityApmAgentsJavaConfigure", + "classic-sources": [ + "enApmAgentJavaConfiguration", + "enApmAgentJavaConfigCircuitBreaker", + "enApmAgentJavaConfigCore", + "enApmAgentJavaConfigDatastore", + "enApmAgentJavaConfigHttp", + "enApmAgentJavaConfigHugeTraces", + "enApmAgentJavaConfigJaxRs", + "enApmAgentJavaConfigJmx", + "enApmAgentJavaConfigLogging", + "enApmAgentJavaConfigMessaging", + "enApmAgentJavaConfigMetrics", + "enApmAgentJavaConfigProfiling", + "enApmAgentJavaConfigReferencePropertiesFile", + "enApmAgentJavaConfigReporter", + "enApmAgentJavaConfigServerless", + "enApmAgentJavaConfigStacktrace" + ] + }, + { + "id": "serverlessObservabilityApmAgentsJavaApi", + "classic-sources": [ + "enApmAgentJavaApis", + "enApmAgentJavaPublicApi", + "enApmAgentJavaOpentelemetryBridge", + "enApmAgentJavaOpentracingBridge", + "enApmAgentJavaPluginApi" + ] + }, + { + "id": "serverlessObservabilityApmAgentsJavaPerformanceTuning", + "classic-sources": [ "enApmAgentJavaTuningAndOverhead" ] } ] }, { "id": "serverlessObservabilityApmAgentsNet", + "classic-sources": [ "enApmAgentDotnetIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsNetGetStarted" + "id": "serverlessObservabilityApmAgentsNetGetStarted", + "classic-sources": [ + "enApmAgentDotnetSetup", + "enApmAgentDotnetSetupAutoInstrumentation", + "enApmAgentDotnetSetupAspDotNet", + "enApmAgentDotnetSetupDotnetNetCore", + "enApmAgentDotnetSetupAspDotNet", + "enApmAgentDotnetSetupAzureFunctions", + "enApmAgentDotnetSetupGeneral" + ] }, { - "id": "serverlessObservabilityApmAgentsNetSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsNetSupportedTechnologies", + "classic-sources": [ "enApmAgentDotnetSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsNetInstall" + "id": "serverlessObservabilityApmAgentsNetInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsNetConfigure" + "id": "serverlessObservabilityApmAgentsNetConfigure", + "classic-sources": [ + "enApmAgentDotnetConfiguration", + "enApmAgentDotnetConfigurationOnAspNet", + "enApmAgentDotnetConfigurationForWindowsServices", + "enApmAgentDotnetConfigurationOnAspNet", + "enApmAgentDotnetConfigCore", + "enApmAgentDotnetConfigReporter", + "enApmAgentDotnetConfigHttp", + "enApmAgentDotnetConfigMessaging", + "enApmAgentDotnetConfigStacktrace", + "enApmAgentDotnetConfigSupportability", + "enApmAgentDotnetConfigAllOptionsSummary" + ] }, { - "id": "serverlessObservabilityApmAgentsNetApi" + "id": "serverlessObservabilityApmAgentsNetApi", + "classic-sources": [ + "enApmAgentDotnetPublicApi" + ] }, { - "id": "serverlessObservabilityApmAgentsNetPerformanceTuning" + "id": "serverlessObservabilityApmAgentsNetPerformanceTuning", + "classic-sources": [ + "enApmAgentDotnetPerformanceTuning" + ] } ] }, { "id": "serverlessObservabilityApmAgentsNodejs", + "classic-sources": [ "enApmAgentNodejsIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsNodejsGetStarted" + "id": "serverlessObservabilityApmAgentsNodejsGetStarted", + "classic-sources": [ + "enApmAgentNodejsSetUp", + "enApmAgentNodejsLambda", + "enApmAgentNodejsAzureFunctions", + "enApmAgentNodejsExpress", + "enApmAgentNodejsFastify", + "enApmAgentNodejsHapi", + "enApmAgentNodejsKoa", + "enApmAgentNodejsNextjs", + "enApmAgentNodejsRestify", + "enApmAgentNodejsTypescript", + "enApmAgentNodejsCustomStack", + "enApmAgentNodejsStartingTheAgent" + ] }, { - "id": "serverlessObservabilityApmAgentsNodejsSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsNodejsSupportedTechnologies", + "classic-sources": [ "enApmAgentNodejsSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsNodejsInstall" + "id": "serverlessObservabilityApmAgentsNodejsInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsNodejsConfigure" + "id": "serverlessObservabilityApmAgentsNodejsConfigure", + "classic-sources": [ + "enApmAgentNodejsAdvancedSetup", + "enApmAgentNodejsConfiguringTheAgent", + "enApmAgentNodejsConfiguration", + "enApmAgentNodejsCustomTransactions", + "enApmAgentNodejsCustomSpans" + ] }, { - "id": "serverlessObservabilityApmAgentsNodejsApi" + "id": "serverlessObservabilityApmAgentsNodejsApi", + "classic-sources": [ + "enApmAgentNodejsApi", + "enApmAgentNodejsAgentApi", + "enApmAgentNodejsTransactionApi", + "enApmAgentNodejsSpanApi" + ] }, { - "id": "serverlessObservabilityApmAgentsNodejsPerformanceTuning" + "id": "serverlessObservabilityApmAgentsNodejsPerformanceTuning", + "classic-sources": [ "enApmAgentNodejsPerformanceTuning" ] } ] }, { "id": "serverlessObservabilityApmAgentsPhp", + "classic-sources": [ "enApmAgentPhpIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsPhpGetStarted" + "id": "serverlessObservabilityApmAgentsPhpGetStarted", + "classic-sources": [ "enApmAgentPhpSetup" ] }, { - "id": "serverlessObservabilityApmAgentsPhpSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsPhpSupportedTechnologies", + "classic-sources": [ "enApmAgentPhpSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsPhpInstall" + "id": "serverlessObservabilityApmAgentsPhpInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsPhpConfigure" + "id": "serverlessObservabilityApmAgentsPhpConfigure", + "classic-sources": [ + "enApmAgentPhpConfiguration", + "enApmAgentPhpConfigurationReference" + ] }, { - "id": "serverlessObservabilityApmAgentsPhpApi" + "id": "serverlessObservabilityApmAgentsPhpApi", + "classic-sources": [ + "enApmAgentPhpPublicApi" + ] }, { - "id": "serverlessObservabilityApmAgentsPhpPerformanceTuning" + "id": "serverlessObservabilityApmAgentsPhpPerformanceTuning", + "classic-sources": [] } ] }, { "id": "serverlessObservabilityApmAgentsPython", + "classic-sources": [ "enApmAgentPythonGettingStarted" ], "items": [ { - "id": "serverlessObservabilityApmAgentsPythonGetStarted" + "id": "serverlessObservabilityApmAgentsPythonGetStarted", + "classic-sources": [ + "enApmAgentPythonSetUp", + "enApmAgentPythonDjangoSupport", + "enApmAgentPythonFlaskSupport", + "enApmAgentPythonAiohttpServerSupport", + "enApmAgentPythonTornadoSupport", + "enApmAgentPythonStarletteSupport", + "enApmAgentPythonSanicSupport", + "enApmAgentPythonLambdaSupport", + "enApmAgentPythonAzureFunctionsSupport", + "enApmAgentPythonWrapperSupport" + ] }, { - "id": "serverlessObservabilityApmAgentsPythonSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsPythonSupportedTechnologies", + "classic-sources": [ "enApmAgentPythonSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsPythonInstall" + "id": "serverlessObservabilityApmAgentsPythonInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsPythonConfigure" + "id": "serverlessObservabilityApmAgentsPythonConfigure", + "classic-sources": [ "enApmAgentPythonConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsPythonApi" + "id": "serverlessObservabilityApmAgentsPythonApi", + "classic-sources": [ "enApmAgentPythonApi" ] }, { - "id": "serverlessObservabilityApmAgentsPythonPerformanceTuning" + "id": "serverlessObservabilityApmAgentsPythonPerformanceTuning", + "classic-sources": [ "enApmAgentPythonTuningAndOverhead" ] } ] }, { "id": "serverlessObservabilityApmAgentsRuby", + "classic-sources": [ "enApmAgentRubyIntroduction" ], "items": [ { - "id": "serverlessObservabilityApmAgentsRubyGetStarted" + "id": "serverlessObservabilityApmAgentsRubyGetStarted", + "classic-sources": [ + "enApmAgentRubySetUp", + "enApmAgentRubyGettingStartedRails", + "enApmAgentRubyGettingStartedRack" + ] }, { - "id": "serverlessObservabilityApmAgentsRubySupportedTechnologies" + "id": "serverlessObservabilityApmAgentsRubySupportedTechnologies", + "classic-sources": [ "enApmAgentRubySupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsRubyInstall" + "id": "serverlessObservabilityApmAgentsRubyInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsRubyConfigure" + "id": "serverlessObservabilityApmAgentsRubyConfigure", + "classic-sources": [ "enApmAgentRubyConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsRubyApi" + "id": "serverlessObservabilityApmAgentsRubyApi", + "classic-sources": [ "enApmAgentRubyApi" ] }, { - "id": "serverlessObservabilityApmAgentsRubyPerformanceTuning" + "id": "serverlessObservabilityApmAgentsRubyPerformanceTuning", + "classic-sources": [ "enApmAgentRubyTuningAndOverhead" ] } ] }, { "id": "serverlessObservabilityApmAgentsRum", + "classic-sources": [ "enApmAgentRumJsIntro" ], "items": [ { - "id": "serverlessObservabilityApmAgentsRumGetStarted" + "id": "serverlessObservabilityApmAgentsRumGetStarted", + "classic-sources": [ + "enApmAgentRumJsGettingStarted", + "enApmAgentRumJsInstallTheAgent", + "enApmAgentRumJsConfiguringCors" + ] }, { - "id": "serverlessObservabilityApmAgentsRumSupportedTechnologies" + "id": "serverlessObservabilityApmAgentsRumSupportedTechnologies", + "classic-sources": [ "enApmAgentRumJsSupportedTechnologies" ] }, { - "id": "serverlessObservabilityApmAgentsRumInstall" + "id": "serverlessObservabilityApmAgentsRumInstall", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsRumConfigure" + "id": "serverlessObservabilityApmAgentsRumConfigure", + "classic-sources": [ "enApmAgentRumJsConfiguration" ] }, { - "id": "serverlessObservabilityApmAgentsRumApi" + "id": "serverlessObservabilityApmAgentsRumApi", + "classic-sources": [ + "enApmAgentRumJsApi", + "enApmAgentRumJsAgentApi", + "enApmAgentRumJsTransactionApi", + "enApmAgentRumJsSpanApi" + ] }, { - "id": "serverlessObservabilityApmAgentsRumPerformanceTuning" + "id": "serverlessObservabilityApmAgentsRumPerformanceTuning", + "classic-sources": [ "enApmAgentRumJsPerformanceTuning" ] } ] }, @@ -304,22 +481,28 @@ "id": "serverlessObservabilityApmAgentsOtel", "items": [ { - "id": "serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents" + "id": "serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport" + "id": "serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments" + "id": "serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsOtelCollectMetrics" + "id": "serverlessObservabilityApmAgentsOtelCollectMetrics", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsOtelLimitations" + "id": "serverlessObservabilityApmAgentsOtelLimitations", + "classic-sources": [] }, { - "id": "serverlessObservabilityApmAgentsOtelResourceAttributes" + "id": "serverlessObservabilityApmAgentsOtelResourceAttributes", + "classic-sources": [] } ] }, From a300ad83d3b96a2e5928f187e025589ec104ad63 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Aug 2023 18:50:24 -0500 Subject: [PATCH 3/4] rename files, update slugs --- ...es-to-elastic-android-api.mdx => apm-agents-android-api.mdx} | 2 +- ...c-android-configure.mdx => apm-agents-android-configure.mdx} | 2 +- ...droid-get-started.mdx => apm-agents-android-get-started.mdx} | 2 +- ...astic-android-install.mdx => apm-agents-android-install.mdx} | 2 +- ...nce-tuning.mdx => apm-agents-android-performance-tuning.mdx} | 2 +- ...logies.mdx => apm-agents-android-supported-technologies.mdx} | 2 +- ...end-traces-to-elastic-android.mdx => apm-agents-android.mdx} | 2 +- ...elastic-apm-agents.mdx => apm-agents-elastic-apm-agents.mdx} | 2 +- ...-send-traces-to-elastic-go-api.mdx => apm-agents-go-api.mdx} | 2 +- ...-to-elastic-go-configure.mdx => apm-agents-go-configure.mdx} | 2 +- ...elastic-go-get-started.mdx => apm-agents-go-get-started.mdx} | 2 +- ...aces-to-elastic-go-install.mdx => apm-agents-go-install.mdx} | 2 +- ...formance-tuning.mdx => apm-agents-go-performance-tuning.mdx} | 2 +- ...echnologies.mdx => apm-agents-go-supported-technologies.mdx} | 2 +- ...ance-apm-send-traces-to-elastic-go.mdx => apm-agents-go.mdx} | 2 +- ...end-traces-to-elastic-ios-api.mdx => apm-agents-ios-api.mdx} | 2 +- ...o-elastic-ios-configure.mdx => apm-agents-ios-configure.mdx} | 2 +- ...astic-ios-get-started.mdx => apm-agents-ios-get-started.mdx} | 2 +- ...es-to-elastic-ios-install.mdx => apm-agents-ios-install.mdx} | 2 +- ...ormance-tuning.mdx => apm-agents-ios-performance-tuning.mdx} | 2 +- ...chnologies.mdx => apm-agents-ios-supported-technologies.mdx} | 2 +- ...ce-apm-send-traces-to-elastic-ios.mdx => apm-agents-ios.mdx} | 2 +- ...d-traces-to-elastic-java-api.mdx => apm-agents-java-api.mdx} | 2 +- ...elastic-java-configure.mdx => apm-agents-java-configure.mdx} | 2 +- ...tic-java-get-started.mdx => apm-agents-java-get-started.mdx} | 2 +- ...-to-elastic-java-install.mdx => apm-agents-java-install.mdx} | 2 +- ...rmance-tuning.mdx => apm-agents-java-performance-tuning.mdx} | 2 +- ...hnologies.mdx => apm-agents-java-supported-technologies.mdx} | 2 +- ...-apm-send-traces-to-elastic-java.mdx => apm-agents-java.mdx} | 2 +- ...end-traces-to-elastic-net-api.mdx => apm-agents-net-api.mdx} | 2 +- ...o-elastic-net-configure.mdx => apm-agents-net-configure.mdx} | 2 +- ...astic-net-get-started.mdx => apm-agents-net-get-started.mdx} | 2 +- ...es-to-elastic-net-install.mdx => apm-agents-net-install.mdx} | 2 +- ...ormance-tuning.mdx => apm-agents-net-performance-tuning.mdx} | 2 +- ...chnologies.mdx => apm-agents-net-supported-technologies.mdx} | 2 +- ...ce-apm-send-traces-to-elastic-net.mdx => apm-agents-net.mdx} | 2 +- ...aces-to-elastic-nodejs-api.mdx => apm-agents-nodejs-api.mdx} | 2 +- ...tic-nodejs-configure.mdx => apm-agents-nodejs-configure.mdx} | 2 +- ...nodejs-get-started.mdx => apm-agents-nodejs-get-started.mdx} | 2 +- ...elastic-nodejs-install.mdx => apm-agents-nodejs-install.mdx} | 2 +- ...ance-tuning.mdx => apm-agents-nodejs-performance-tuning.mdx} | 2 +- ...ologies.mdx => apm-agents-nodejs-supported-technologies.mdx} | 2 +- ...-send-traces-to-elastic-nodejs.mdx => apm-agents-nodejs.mdx} | 2 +- ...metrics.mdx => apm-agents-opentelemetry-collect-metrics.mdx} | 2 +- ...limitations.mdx => apm-agents-opentelemetry-limitations.mdx} | 2 +- ...ntelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx} | 2 +- ...> apm-agents-opentelemetry-opentelemetry-native-support.mdx} | 2 +- ...> apm-agents-opentelemetry-other-execution-environments.mdx} | 2 +- ...tes.mdx => apm-agents-opentelemetry-resource-attributes.mdx} | 2 +- ...o-elastic-opentelemetry.mdx => apm-agents-opentelemetry.mdx} | 2 +- ...end-traces-to-elastic-php-api.mdx => apm-agents-php-api.mdx} | 2 +- ...o-elastic-php-configure.mdx => apm-agents-php-configure.mdx} | 2 +- ...astic-php-get-started.mdx => apm-agents-php-get-started.mdx} | 2 +- ...es-to-elastic-php-install.mdx => apm-agents-php-install.mdx} | 2 +- ...ormance-tuning.mdx => apm-agents-php-performance-tuning.mdx} | 2 +- ...chnologies.mdx => apm-agents-php-supported-technologies.mdx} | 2 +- ...ce-apm-send-traces-to-elastic-php.mdx => apm-agents-php.mdx} | 2 +- ...aces-to-elastic-python-api.mdx => apm-agents-python-api.mdx} | 2 +- ...tic-python-configure.mdx => apm-agents-python-configure.mdx} | 2 +- ...python-get-started.mdx => apm-agents-python-get-started.mdx} | 2 +- ...elastic-python-install.mdx => apm-agents-python-install.mdx} | 2 +- ...ance-tuning.mdx => apm-agents-python-performance-tuning.mdx} | 2 +- ...ologies.mdx => apm-agents-python-supported-technologies.mdx} | 2 +- ...-send-traces-to-elastic-python.mdx => apm-agents-python.mdx} | 2 +- ...d-traces-to-elastic-ruby-api.mdx => apm-agents-ruby-api.mdx} | 2 +- ...elastic-ruby-configure.mdx => apm-agents-ruby-configure.mdx} | 2 +- ...tic-ruby-get-started.mdx => apm-agents-ruby-get-started.mdx} | 2 +- ...-to-elastic-ruby-install.mdx => apm-agents-ruby-install.mdx} | 2 +- ...rmance-tuning.mdx => apm-agents-ruby-performance-tuning.mdx} | 2 +- ...hnologies.mdx => apm-agents-ruby-supported-technologies.mdx} | 2 +- ...-apm-send-traces-to-elastic-ruby.mdx => apm-agents-ruby.mdx} | 2 +- ...end-traces-to-elastic-rum-api.mdx => apm-agents-rum-api.mdx} | 2 +- ...o-elastic-rum-configure.mdx => apm-agents-rum-configure.mdx} | 2 +- ...astic-rum-get-started.mdx => apm-agents-rum-get-started.mdx} | 2 +- ...es-to-elastic-rum-install.mdx => apm-agents-rum-install.mdx} | 2 +- ...ormance-tuning.mdx => apm-agents-rum-performance-tuning.mdx} | 2 +- ...chnologies.mdx => apm-agents-rum-supported-technologies.mdx} | 2 +- ...ce-apm-send-traces-to-elastic-rum.mdx => apm-agents-rum.mdx} | 2 +- ...formance-apm-send-traces-to-elastic-aws-lambda-functions.mdx | 2 +- ...pplication-performance-apm-send-traces-to-elastic-jaeger.mdx | 2 +- 80 files changed, 80 insertions(+), 80 deletions(-) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx => apm-agents-android-api.mdx} (64%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx => apm-agents-android-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx => apm-agents-android-get-started.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx => apm-agents-android-install.mdx} (64%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx => apm-agents-android-performance-tuning.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx => apm-agents-android-supported-technologies.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-android.mdx => apm-agents-android.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx => apm-agents-elastic-apm-agents.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx => apm-agents-go-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx => apm-agents-go-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx => apm-agents-go-get-started.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx => apm-agents-go-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx => apm-agents-go-performance-tuning.mdx} (64%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx => apm-agents-go-supported-technologies.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-go.mdx => apm-agents-go.mdx} (97%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx => apm-agents-ios-api.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx => apm-agents-ios-configure.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx => apm-agents-ios-get-started.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx => apm-agents-ios-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx => apm-agents-ios-performance-tuning.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx => apm-agents-ios-supported-technologies.mdx} (79%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ios.mdx => apm-agents-ios.mdx} (97%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx => apm-agents-java-api.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx => apm-agents-java-configure.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx => apm-agents-java-get-started.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx => apm-agents-java-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx => apm-agents-java-performance-tuning.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx => apm-agents-java-supported-technologies.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-java.mdx => apm-agents-java.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx => apm-agents-net-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx => apm-agents-net-configure.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx => apm-agents-net-get-started.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx => apm-agents-net-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx => apm-agents-net-performance-tuning.mdx} (97%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx => apm-agents-net-supported-technologies.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-net.mdx => apm-agents-net.mdx} (96%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx => apm-agents-nodejs-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx => apm-agents-nodejs-configure.mdx} (89%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx => apm-agents-nodejs-get-started.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx => apm-agents-nodejs-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx => apm-agents-nodejs-performance-tuning.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx => apm-agents-nodejs-supported-technologies.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx => apm-agents-nodejs.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx => apm-agents-opentelemetry-collect-metrics.mdx} (62%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx => apm-agents-opentelemetry-limitations.mdx} (62%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx => apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx => apm-agents-opentelemetry-opentelemetry-native-support.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx => apm-agents-opentelemetry-other-execution-environments.mdx} (62%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx => apm-agents-opentelemetry-resource-attributes.mdx} (62%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx => apm-agents-opentelemetry.mdx} (64%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx => apm-agents-php-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx => apm-agents-php-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx => apm-agents-php-get-started.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx => apm-agents-php-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx => apm-agents-php-performance-tuning.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx => apm-agents-php-supported-technologies.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-php.mdx => apm-agents-php.mdx} (92%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx => apm-agents-python-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx => apm-agents-python-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx => apm-agents-python-get-started.mdx} (97%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx => apm-agents-python-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx => apm-agents-python-performance-tuning.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx => apm-agents-python-supported-technologies.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-python.mdx => apm-agents-python.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx => apm-agents-ruby-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx => apm-agents-ruby-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx => apm-agents-ruby-get-started.mdx} (94%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx => apm-agents-ruby-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx => apm-agents-ruby-performance-tuning.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx => apm-agents-ruby-supported-technologies.mdx} (97%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx => apm-agents-ruby.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx => apm-agents-rum-api.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx => apm-agents-rum-configure.mdx} (99%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx => apm-agents-rum-get-started.mdx} (94%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx => apm-agents-rum-install.mdx} (63%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx => apm-agents-rum-performance-tuning.mdx} (95%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx => apm-agents-rum-supported-technologies.mdx} (98%) rename docs/{monitor-application-performance-apm-send-traces-to-elastic-rum.mdx => apm-agents-rum.mdx} (96%) diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx b/docs/apm-agents-android-api.mdx similarity index 64% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx rename to docs/apm-agents-android-api.mdx index 13d1e5ab24..90d53fc165 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-api.mdx +++ b/docs/apm-agents-android-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-api +slug: /serverless/observability/apm-agents-android-api title: API # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx b/docs/apm-agents-android-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx rename to docs/apm-agents-android-configure.mdx index edc210d296..c88235eaca 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-configure.mdx +++ b/docs/apm-agents-android-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-configure +slug: /serverless/observability/apm-agents-android-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx b/docs/apm-agents-android-get-started.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx rename to docs/apm-agents-android-get-started.mdx index 4842209175..e36c4bd719 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-get-started.mdx +++ b/docs/apm-agents-android-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-get-started +slug: /serverless/observability/apm-agents-android-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx b/docs/apm-agents-android-install.mdx similarity index 64% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx rename to docs/apm-agents-android-install.mdx index a2cb08b6c7..fd59a0d045 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-install.mdx +++ b/docs/apm-agents-android-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-install +slug: /serverless/observability/apm-agents-android-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx b/docs/apm-agents-android-performance-tuning.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx rename to docs/apm-agents-android-performance-tuning.mdx index f958f217f3..4b1937d233 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning.mdx +++ b/docs/apm-agents-android-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-performance-tuning +slug: /serverless/observability/apm-agents-android-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx b/docs/apm-agents-android-supported-technologies.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx rename to docs/apm-agents-android-supported-technologies.mdx index 27316718a1..b47a05041a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies.mdx +++ b/docs/apm-agents-android-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroidSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android-supported-technologies +slug: /serverless/observability/apm-agents-android-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx b/docs/apm-agents-android.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx rename to docs/apm-agents-android.mdx index 1860f3cec7..79f4ca7c60 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-android.mdx +++ b/docs/apm-agents-android.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsAndroid -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-android +slug: /serverless/observability/apm-agents-android title: Android # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx b/docs/apm-agents-elastic-apm-agents.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx rename to docs/apm-agents-elastic-apm-agents.mdx index c12c6d3f92..1c22a3edd8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents.mdx +++ b/docs/apm-agents-elastic-apm-agents.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgents -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-elastic-apm-agents +slug: /serverless/observability/apm-agents-elastic-apm-agents title: Elastic APM agents # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx b/docs/apm-agents-go-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx rename to docs/apm-agents-go-api.mdx index 1d78b5a598..9c2e0c2998 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-api.mdx +++ b/docs/apm-agents-go-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-api +slug: /serverless/observability/apm-agents-go-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx b/docs/apm-agents-go-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx rename to docs/apm-agents-go-configure.mdx index 5809c3281b..64402e9bc5 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-configure.mdx +++ b/docs/apm-agents-go-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-configure +slug: /serverless/observability/apm-agents-go-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx b/docs/apm-agents-go-get-started.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx rename to docs/apm-agents-go-get-started.mdx index c805040f5e..b3ae58381f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-get-started.mdx +++ b/docs/apm-agents-go-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-get-started +slug: /serverless/observability/apm-agents-go-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx b/docs/apm-agents-go-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx rename to docs/apm-agents-go-install.mdx index 3fcdc90a67..8805349287 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-install.mdx +++ b/docs/apm-agents-go-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-install +slug: /serverless/observability/apm-agents-go-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx b/docs/apm-agents-go-performance-tuning.mdx similarity index 64% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx rename to docs/apm-agents-go-performance-tuning.mdx index 1d70ebcc1b..4dbc139c5b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning.mdx +++ b/docs/apm-agents-go-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-performance-tuning +slug: /serverless/observability/apm-agents-go-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx b/docs/apm-agents-go-supported-technologies.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx rename to docs/apm-agents-go-supported-technologies.mdx index d322776a7b..87db018586 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies.mdx +++ b/docs/apm-agents-go-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGoSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go-supported-technologies +slug: /serverless/observability/apm-agents-go-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx b/docs/apm-agents-go.mdx similarity index 97% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx rename to docs/apm-agents-go.mdx index d2d8296c31..707469834a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-go.mdx +++ b/docs/apm-agents-go.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsGo -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-go +slug: /serverless/observability/apm-agents-go title: Go # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx b/docs/apm-agents-ios-api.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx rename to docs/apm-agents-ios-api.mdx index 41171dffdc..9fd46a9bac 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-api.mdx +++ b/docs/apm-agents-ios-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-api +slug: /serverless/observability/apm-agents-ios-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx b/docs/apm-agents-ios-configure.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx rename to docs/apm-agents-ios-configure.mdx index c5f1e60471..ba24f02333 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-configure.mdx +++ b/docs/apm-agents-ios-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-configure +slug: /serverless/observability/apm-agents-ios-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx b/docs/apm-agents-ios-get-started.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx rename to docs/apm-agents-ios-get-started.mdx index 2f000e46cc..5f89f0a70f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started.mdx +++ b/docs/apm-agents-ios-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-get-started +slug: /serverless/observability/apm-agents-ios-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx b/docs/apm-agents-ios-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx rename to docs/apm-agents-ios-install.mdx index 1c9d88de3b..78e68fbe10 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-install.mdx +++ b/docs/apm-agents-ios-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-install +slug: /serverless/observability/apm-agents-ios-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx b/docs/apm-agents-ios-performance-tuning.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx rename to docs/apm-agents-ios-performance-tuning.mdx index 6630e619ce..4216cc577f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning.mdx +++ b/docs/apm-agents-ios-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-performance-tuning +slug: /serverless/observability/apm-agents-ios-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx b/docs/apm-agents-ios-supported-technologies.mdx similarity index 79% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx rename to docs/apm-agents-ios-supported-technologies.mdx index af3f4c93fc..3a0ecdb34f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies.mdx +++ b/docs/apm-agents-ios-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIosSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios-supported-technologies +slug: /serverless/observability/apm-agents-ios-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx b/docs/apm-agents-ios.mdx similarity index 97% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx rename to docs/apm-agents-ios.mdx index fdd59ff2e9..453e250fba 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ios.mdx +++ b/docs/apm-agents-ios.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsIos -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ios +slug: /serverless/observability/apm-agents-ios title: iOS # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx b/docs/apm-agents-java-api.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx rename to docs/apm-agents-java-api.mdx index 40c1fa4917..54399b59e8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-api.mdx +++ b/docs/apm-agents-java-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-api +slug: /serverless/observability/apm-agents-java-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx b/docs/apm-agents-java-configure.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx rename to docs/apm-agents-java-configure.mdx index 8038090532..227f1d9d81 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-configure.mdx +++ b/docs/apm-agents-java-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-configure +slug: /serverless/observability/apm-agents-java-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx b/docs/apm-agents-java-get-started.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx rename to docs/apm-agents-java-get-started.mdx index cb21b7f7b0..1d43553dab 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-get-started.mdx +++ b/docs/apm-agents-java-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-get-started +slug: /serverless/observability/apm-agents-java-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx b/docs/apm-agents-java-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx rename to docs/apm-agents-java-install.mdx index fc8318f42b..3c494fb579 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-install.mdx +++ b/docs/apm-agents-java-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-install +slug: /serverless/observability/apm-agents-java-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx b/docs/apm-agents-java-performance-tuning.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx rename to docs/apm-agents-java-performance-tuning.mdx index 0534fa0977..d27f090134 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning.mdx +++ b/docs/apm-agents-java-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-performance-tuning +slug: /serverless/observability/apm-agents-java-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx b/docs/apm-agents-java-supported-technologies.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx rename to docs/apm-agents-java-supported-technologies.mdx index 50d712f633..281d13d434 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies.mdx +++ b/docs/apm-agents-java-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJavaSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java-supported-technologies +slug: /serverless/observability/apm-agents-java-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx b/docs/apm-agents-java.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx rename to docs/apm-agents-java.mdx index 2fcd25d488..eccaac3bd8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-java.mdx +++ b/docs/apm-agents-java.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsJava -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-java +slug: /serverless/observability/apm-agents-java title: Java # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx b/docs/apm-agents-net-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx rename to docs/apm-agents-net-api.mdx index 4dd2240d55..e6bf1701a5 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-api.mdx +++ b/docs/apm-agents-net-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-api +slug: /serverless/observability/apm-agents-net-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx b/docs/apm-agents-net-configure.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx rename to docs/apm-agents-net-configure.mdx index b79bb18123..b48480d860 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-configure.mdx +++ b/docs/apm-agents-net-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-configure +slug: /serverless/observability/apm-agents-net-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx b/docs/apm-agents-net-get-started.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx rename to docs/apm-agents-net-get-started.mdx index 6995eee6af..8c41a2f358 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-get-started.mdx +++ b/docs/apm-agents-net-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-get-started +slug: /serverless/observability/apm-agents-net-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx b/docs/apm-agents-net-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx rename to docs/apm-agents-net-install.mdx index 3bbb70119c..0e920c6fd1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-install.mdx +++ b/docs/apm-agents-net-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-install +slug: /serverless/observability/apm-agents-net-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx b/docs/apm-agents-net-performance-tuning.mdx similarity index 97% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx rename to docs/apm-agents-net-performance-tuning.mdx index fff061b533..45deb29d40 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning.mdx +++ b/docs/apm-agents-net-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-performance-tuning +slug: /serverless/observability/apm-agents-net-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx b/docs/apm-agents-net-supported-technologies.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx rename to docs/apm-agents-net-supported-technologies.mdx index a6c020c3e2..84d5773962 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies.mdx +++ b/docs/apm-agents-net-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNetSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net-supported-technologies +slug: /serverless/observability/apm-agents-net-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx b/docs/apm-agents-net.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx rename to docs/apm-agents-net.mdx index c192be3131..3aa5fcc0d1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-net.mdx +++ b/docs/apm-agents-net.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNet -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-net +slug: /serverless/observability/apm-agents-net title: .NET # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx b/docs/apm-agents-nodejs-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx rename to docs/apm-agents-nodejs-api.mdx index a08dc0df7c..092c3171e1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api.mdx +++ b/docs/apm-agents-nodejs-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-api +slug: /serverless/observability/apm-agents-nodejs-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx b/docs/apm-agents-nodejs-configure.mdx similarity index 89% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx rename to docs/apm-agents-nodejs-configure.mdx index 49dcb9b537..70769a2ac0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure.mdx +++ b/docs/apm-agents-nodejs-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-configure +slug: /serverless/observability/apm-agents-nodejs-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx b/docs/apm-agents-nodejs-get-started.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx rename to docs/apm-agents-nodejs-get-started.mdx index a2c9db0106..485423d108 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started.mdx +++ b/docs/apm-agents-nodejs-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-get-started +slug: /serverless/observability/apm-agents-nodejs-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx b/docs/apm-agents-nodejs-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx rename to docs/apm-agents-nodejs-install.mdx index 38fa62391d..a699cddbf8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install.mdx +++ b/docs/apm-agents-nodejs-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-install +slug: /serverless/observability/apm-agents-nodejs-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx b/docs/apm-agents-nodejs-performance-tuning.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx rename to docs/apm-agents-nodejs-performance-tuning.mdx index 8dab4e68e5..64c0a3b108 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning.mdx +++ b/docs/apm-agents-nodejs-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-performance-tuning +slug: /serverless/observability/apm-agents-nodejs-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx b/docs/apm-agents-nodejs-supported-technologies.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx rename to docs/apm-agents-nodejs-supported-technologies.mdx index 741116b0d6..177c97541f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies.mdx +++ b/docs/apm-agents-nodejs-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejsSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs-supported-technologies +slug: /serverless/observability/apm-agents-nodejs-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx b/docs/apm-agents-nodejs.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx rename to docs/apm-agents-nodejs.mdx index f8d7ab6c39..c8d77f61ee 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-nodejs.mdx +++ b/docs/apm-agents-nodejs.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsNodejs -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-nodejs +slug: /serverless/observability/apm-agents-nodejs title: Node.js # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx b/docs/apm-agents-opentelemetry-collect-metrics.mdx similarity index 62% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx rename to docs/apm-agents-opentelemetry-collect-metrics.mdx index db2ab26b6f..572dc1601a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics.mdx +++ b/docs/apm-agents-opentelemetry-collect-metrics.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelCollectMetrics -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-collect-metrics +slug: /serverless/observability/apm-agents-opentelemetry-collect-metrics title: Collect metrics # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx b/docs/apm-agents-opentelemetry-limitations.mdx similarity index 62% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx rename to docs/apm-agents-opentelemetry-limitations.mdx index 4e6bf06560..2a0ed4f750 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations.mdx +++ b/docs/apm-agents-opentelemetry-limitations.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelLimitations -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-limitations +slug: /serverless/observability/apm-agents-opentelemetry-limitations title: Limitations # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx b/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx rename to docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx index 6f5f5f2d6b..35267a75c4 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx +++ b/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents +slug: /serverless/observability/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents title: OpenTelemetry API/SDK with Elastic APM agents # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx b/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx rename to docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx index 3e39acfb7e..97be9691e1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support.mdx +++ b/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-opentelemetry-native-support +slug: /serverless/observability/apm-agents-opentelemetry-opentelemetry-native-support title: OpenTelemetry native support # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx b/docs/apm-agents-opentelemetry-other-execution-environments.mdx similarity index 62% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx rename to docs/apm-agents-opentelemetry-other-execution-environments.mdx index 83b506fb80..6535ca144b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments.mdx +++ b/docs/apm-agents-opentelemetry-other-execution-environments.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-other-execution-environments +slug: /serverless/observability/apm-agents-opentelemetry-other-execution-environments title: Other execution environments # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx b/docs/apm-agents-opentelemetry-resource-attributes.mdx similarity index 62% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx rename to docs/apm-agents-opentelemetry-resource-attributes.mdx index af2f26f632..f107d520ae 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes.mdx +++ b/docs/apm-agents-opentelemetry-resource-attributes.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtelResourceAttributes -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry-resource-attributes +slug: /serverless/observability/apm-agents-opentelemetry-resource-attributes title: Resource attributes # description: Description to be written tags: [ 'serverless', 'observability', 'how-to' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx b/docs/apm-agents-opentelemetry.mdx similarity index 64% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx rename to docs/apm-agents-opentelemetry.mdx index de8fbc01c0..540eaa0c82 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry.mdx +++ b/docs/apm-agents-opentelemetry.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsOtel -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-opentelemetry +slug: /serverless/observability/apm-agents-opentelemetry title: OpenTelemetry # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx b/docs/apm-agents-php-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx rename to docs/apm-agents-php-api.mdx index bf231b6e5b..d0d9403479 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-api.mdx +++ b/docs/apm-agents-php-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-api +slug: /serverless/observability/apm-agents-php-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx b/docs/apm-agents-php-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx rename to docs/apm-agents-php-configure.mdx index 949f005743..8b27d86404 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-configure.mdx +++ b/docs/apm-agents-php-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-configure +slug: /serverless/observability/apm-agents-php-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx b/docs/apm-agents-php-get-started.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx rename to docs/apm-agents-php-get-started.mdx index c939622db5..2a9bf2d7ce 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-get-started.mdx +++ b/docs/apm-agents-php-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-get-started +slug: /serverless/observability/apm-agents-php-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx b/docs/apm-agents-php-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx rename to docs/apm-agents-php-install.mdx index 0e102cd1a2..4de46ee2b8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-install.mdx +++ b/docs/apm-agents-php-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-install +slug: /serverless/observability/apm-agents-php-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx b/docs/apm-agents-php-performance-tuning.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx rename to docs/apm-agents-php-performance-tuning.mdx index b03c49abb1..3b033c6911 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning.mdx +++ b/docs/apm-agents-php-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-performance-tuning +slug: /serverless/observability/apm-agents-php-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx b/docs/apm-agents-php-supported-technologies.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx rename to docs/apm-agents-php-supported-technologies.mdx index 3801f68546..17bef6b0a6 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies.mdx +++ b/docs/apm-agents-php-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhpSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php-supported-technologies +slug: /serverless/observability/apm-agents-php-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx b/docs/apm-agents-php.mdx similarity index 92% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx rename to docs/apm-agents-php.mdx index d9c9e35019..bb47521e8d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-php.mdx +++ b/docs/apm-agents-php.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPhp -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-php +slug: /serverless/observability/apm-agents-php title: PHP # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx b/docs/apm-agents-python-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx rename to docs/apm-agents-python-api.mdx index 0507b9e05c..fbb60ec75d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-api.mdx +++ b/docs/apm-agents-python-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-api +slug: /serverless/observability/apm-agents-python-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx b/docs/apm-agents-python-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx rename to docs/apm-agents-python-configure.mdx index 2348c0bfe0..d25939d13f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-configure.mdx +++ b/docs/apm-agents-python-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-configure +slug: /serverless/observability/apm-agents-python-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx b/docs/apm-agents-python-get-started.mdx similarity index 97% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx rename to docs/apm-agents-python-get-started.mdx index 05eaa4b189..02bf6aa4e0 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-get-started.mdx +++ b/docs/apm-agents-python-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-get-started +slug: /serverless/observability/apm-agents-python-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx b/docs/apm-agents-python-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx rename to docs/apm-agents-python-install.mdx index 505d695820..20d76a1e55 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-install.mdx +++ b/docs/apm-agents-python-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-install +slug: /serverless/observability/apm-agents-python-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx b/docs/apm-agents-python-performance-tuning.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx rename to docs/apm-agents-python-performance-tuning.mdx index b5f9406de4..1689a9c86b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning.mdx +++ b/docs/apm-agents-python-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-performance-tuning +slug: /serverless/observability/apm-agents-python-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx b/docs/apm-agents-python-supported-technologies.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx rename to docs/apm-agents-python-supported-technologies.mdx index 30217e8e5a..11840395e8 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies.mdx +++ b/docs/apm-agents-python-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPythonSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python-supported-technologies +slug: /serverless/observability/apm-agents-python-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx b/docs/apm-agents-python.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx rename to docs/apm-agents-python.mdx index 7b4ff69d19..8c5cbf8952 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-python.mdx +++ b/docs/apm-agents-python.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsPython -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-python +slug: /serverless/observability/apm-agents-python title: Python # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx b/docs/apm-agents-ruby-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx rename to docs/apm-agents-ruby-api.mdx index 714be9deae..a303bb6fd9 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-api.mdx +++ b/docs/apm-agents-ruby-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubyApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-api +slug: /serverless/observability/apm-agents-ruby-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx b/docs/apm-agents-ruby-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx rename to docs/apm-agents-ruby-configure.mdx index cde4a34475..de1503f1c1 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure.mdx +++ b/docs/apm-agents-ruby-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubyConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-configure +slug: /serverless/observability/apm-agents-ruby-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx b/docs/apm-agents-ruby-get-started.mdx similarity index 94% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx rename to docs/apm-agents-ruby-get-started.mdx index 594e3594cb..ce889d27b9 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started.mdx +++ b/docs/apm-agents-ruby-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubyGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-get-started +slug: /serverless/observability/apm-agents-ruby-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx b/docs/apm-agents-ruby-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx rename to docs/apm-agents-ruby-install.mdx index d47eac484e..abbb56f61a 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-install.mdx +++ b/docs/apm-agents-ruby-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubyInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-install +slug: /serverless/observability/apm-agents-ruby-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx b/docs/apm-agents-ruby-performance-tuning.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx rename to docs/apm-agents-ruby-performance-tuning.mdx index 271d8e8c11..9d54876c2b 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning.mdx +++ b/docs/apm-agents-ruby-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubyPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-performance-tuning +slug: /serverless/observability/apm-agents-ruby-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx b/docs/apm-agents-ruby-supported-technologies.mdx similarity index 97% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx rename to docs/apm-agents-ruby-supported-technologies.mdx index d8fa71aa73..401fef4f45 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies.mdx +++ b/docs/apm-agents-ruby-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRubySupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby-supported-technologies +slug: /serverless/observability/apm-agents-ruby-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx b/docs/apm-agents-ruby.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx rename to docs/apm-agents-ruby.mdx index 74b3e5d4b6..608d62fc91 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-ruby.mdx +++ b/docs/apm-agents-ruby.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRuby -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-ruby +slug: /serverless/observability/apm-agents-ruby title: Ruby # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx b/docs/apm-agents-rum-api.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx rename to docs/apm-agents-rum-api.mdx index 7c6abdadb1..e89958a25d 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-api.mdx +++ b/docs/apm-agents-rum-api.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumApi -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-api +slug: /serverless/observability/apm-agents-rum-api title: API # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx b/docs/apm-agents-rum-configure.mdx similarity index 99% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx rename to docs/apm-agents-rum-configure.mdx index b70e6dab14..13cee58b3f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-configure.mdx +++ b/docs/apm-agents-rum-configure.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumConfigure -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-configure +slug: /serverless/observability/apm-agents-rum-configure title: Configure # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx b/docs/apm-agents-rum-get-started.mdx similarity index 94% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx rename to docs/apm-agents-rum-get-started.mdx index c12a8b1071..2cadf9baaa 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started.mdx +++ b/docs/apm-agents-rum-get-started.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumGetStarted -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-get-started +slug: /serverless/observability/apm-agents-rum-get-started title: Get started # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx b/docs/apm-agents-rum-install.mdx similarity index 63% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx rename to docs/apm-agents-rum-install.mdx index 8bcdd10679..9d86888541 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-install.mdx +++ b/docs/apm-agents-rum-install.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumInstall -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-install +slug: /serverless/observability/apm-agents-rum-install title: Install # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx b/docs/apm-agents-rum-performance-tuning.mdx similarity index 95% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx rename to docs/apm-agents-rum-performance-tuning.mdx index 3adfe5b653..ed68cc431f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning.mdx +++ b/docs/apm-agents-rum-performance-tuning.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumPerformanceTuning -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-performance-tuning +slug: /serverless/observability/apm-agents-rum-performance-tuning title: Performance tuning # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx b/docs/apm-agents-rum-supported-technologies.mdx similarity index 98% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx rename to docs/apm-agents-rum-supported-technologies.mdx index 7e657a6f12..7591cba73f 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies.mdx +++ b/docs/apm-agents-rum-supported-technologies.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRumSupportedTechnologies -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum-supported-technologies +slug: /serverless/observability/apm-agents-rum-supported-technologies title: Supported technologies # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx b/docs/apm-agents-rum.mdx similarity index 96% rename from docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx rename to docs/apm-agents-rum.mdx index 9b283ead31..2184be71ae 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-rum.mdx +++ b/docs/apm-agents-rum.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityApmAgentsRum -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-rum +slug: /serverless/observability/apm-agents-rum title: RUM # description: Description to be written tags: [ 'serverless', 'observability', '' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx index f560280592..9cf9c416e9 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticAwsLambdaFunctions -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-aws-lambda-functions +slug: /serverless/observability/apm-agents-aws-lambda-functions title: AWS Lambda Functions # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] diff --git a/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx b/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx index 077ad191f4..04422ce2ae 100644 --- a/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx +++ b/docs/monitor-application-performance-apm-send-traces-to-elastic-jaeger.mdx @@ -1,6 +1,6 @@ --- id: serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElasticJaeger -slug: /serverless/observability/monitor-application-performance-apm-send-traces-to-elastic-jaeger +slug: /serverless/observability/apm-agents-jaeger title: Jaeger # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] From 6a31f10e0bcb8774fdeebbb82e0083c751874b75 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 4 Aug 2023 11:55:32 -0500 Subject: [PATCH 4/4] add otel content --- ...m-agents-opentelemetry-collect-metrics.mdx | 92 ++++++++- docs/apm-agents-opentelemetry-limitations.mdx | 40 +++- ...lemetry-apisdk-with-elastic-apm-agents.mdx | 32 ++- ...telemetry-opentelemetry-native-support.mdx | 161 ++++++++++++++- ...telemetry-other-execution-environments.mdx | 185 +++++++++++++++++- ...ents-opentelemetry-resource-attributes.mdx | 42 +++- docs/apm-agents-opentelemetry.mdx | 93 ++++++++- docs/monitor-application-performance-apm.mdx | 22 +++ serverless-observability.docnav.json | 18 +- 9 files changed, 668 insertions(+), 17 deletions(-) diff --git a/docs/apm-agents-opentelemetry-collect-metrics.mdx b/docs/apm-agents-opentelemetry-collect-metrics.mdx index 572dc1601a..9f2893c8d2 100644 --- a/docs/apm-agents-opentelemetry-collect-metrics.mdx +++ b/docs/apm-agents-opentelemetry-collect-metrics.mdx @@ -6,4 +6,94 @@ title: Collect metrics tags: [ 'serverless', 'observability', 'reference' ] --- -No source content found. + +{/* import TabWidgetsOpenKibanaWidget from './transclusion/tab-widgets/open-kibana-widget.mdx' */} + +
+ + +When collecting metrics, please note that the [`DoubleValueRecorder`](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/DoubleValueRecorder.html) +and [`LongValueRecorder`](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/metrics/LongValueObserver.html) metrics are not yet supported. + + +Here's an example of how to capture business metrics from a Java application. + +```java +// initialize metric +Meter meter = GlobalMetricsProvider.getMeter("my-frontend"); +DoubleCounter orderValueCounter = meter.doubleCounterBuilder("order_value").build(); + +public void createOrder(HttpServletRequest request) { + + // create order in the database + ... + // increment business metrics for monitoring + orderValueCounter.add(orderPrice); +} +``` + +See the [Open Telemetry Metrics API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md) +for more information. + +
+ +## Verify OpenTelemetry metrics data + +Use **Discover** to validate that metrics are successfully reported to ((kib)). + +1. Launch ((kib)): + + {/* */} + +1. Open the main menu, then click **Discover**. +1. Select `apm-*` as your index pattern. +1. Filter the data to only show documents with metrics: `processor.name :"metric"` +1. Narrow your search with a known OpenTelemetry field. For example, if you have an `order_value` field, add `order_value: *` to your search to return + only OpenTelemetry metrics documents. + +
+ +## Visualize in ((kib)) + +TSVB within ((kib)) is the recommended visualization for OpenTelemetry metrics. TSVB is a time series data visualizer that allows you to use the +((es)) aggregation framework's full power. With TSVB, you can combine an infinite number of aggregations to display complex data. + +{/* lint ignore ecommerce */} +In this example eCommerce OpenTelemetry dashboard, there are four visualizations: sales, order count, product cache, and system load. The dashboard provides us with business +KPI metrics, along with performance-related metrics. + +{/* ![OpenTelemetry visualizations](images/open-telemetry-collect-metrics/-ecommerce-dashboard.png) */} + +Let's look at how this dashboard was created, specifically the Sales USD and System load visualizations. + +1. Open the main menu, then click **Dashboard**. +1. Click **Create dashboard**. +1. Click **Save**, enter the name of your dashboard, and then click **Save** again. +1. Let’s add a Sales USD visualization. Click **Edit**. +1. Click **Create new** and then select **TSVB**. +1. For the label name, enter Sales USD, and then select the following: + +* Aggregation: `Counter Rate`. +* Field: `order_sum`. +* Scale: `auto`. +* Group by: `Everything` +1. Click **Save**, enter Sales USD as the visualization name, and then click **Save and return**. +1. Now let's create a visualization of load averages on the system. Click **Create new**. +1. Select **TSVB**. +1. Select the following: + +* Aggregation: `Average`. +* Field: `system.cpu.load_average.1m`. +* Group by: `Terms`. +* By: `host.ip`. +* Top: `10`. +* Order by: `Doc Count (default)`. +* Direction: `Descending`. +1. Click **Save**, enter System load per host IP as the visualization name, and then click **Save and return**. + + Both visualizations are now displayed on your custom dashboard. + + +By default, Discover shows data for the last 15 minutes. If you have a time-based index +and no data displays, you might need to increase the time range. + diff --git a/docs/apm-agents-opentelemetry-limitations.mdx b/docs/apm-agents-opentelemetry-limitations.mdx index 2a0ed4f750..e1e77a7d7e 100644 --- a/docs/apm-agents-opentelemetry-limitations.mdx +++ b/docs/apm-agents-opentelemetry-limitations.mdx @@ -6,4 +6,42 @@ title: Limitations tags: [ 'serverless', 'observability', 'overview' ] --- -No source content found. + +
+ +
+ +## OpenTelemetry traces + +* Traces of applications using `messaging` semantics might be wrongly displayed as `transactions` in the APM UI, while they should be considered `spans` (see issue [#7001](https://github.com/elastic/apm-server/issues/7001)). +* Inability to see Stack traces in spans. +* Inability in APM views to view the "Time Spent by Span Type" (see issue [#5747](https://github.com/elastic/apm-server/issues/5747)). + +
+ +## OpenTelemetry metrics + +* Inability to see host metrics in Elastic Metrics Infrastructure view when using the OpenTelemetry Collector host metrics receiver (see issue [#5310](https://github.com/elastic/apm-server/issues/5310)). + +
+ +## OpenTelemetry logs + +* The OpenTelemetry logs intake via APM Server is in technical preview. +* The application logs data stream (`app_logs`) has dynamic mapping disabled. This means the automatic detection and mapping of new fields is disabled (see issue [#9093](https://github.com/elastic/apm-server/issues/9093)). + +
+ +## OpenTelemetry Line Protocol (OTLP) + +APM Server supports both the [(OTLP/gRPC)]({ot_grpc}) and [(OTLP/HTTP)]({ot_http}) protocol with ProtoBuf payload. +APM Server does not yet support JSON Encoding for OTLP/HTTP. + +
+ +## OpenTelemetry Collector exporter for Elastic + +The [OpenTelemetry Collector exporter for Elastic](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticexporter#legacy-opentelemetry-collector-exporter-for-elastic) +was deprecated in 7.13 and replaced by the native support of the OpenTelemetry Line Protocol in +Elastic ((observability)) (OTLP). To learn more, see +[migration](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticexporter#migration). diff --git a/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx b/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx index 35267a75c4..a79b363859 100644 --- a/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx +++ b/docs/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents.mdx @@ -1,9 +1,37 @@ --- -id: serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents +id: serverlessObservabilityApmAgentsOtelApisdkWithElasticApmAgents slug: /serverless/observability/apm-agents-opentelemetry-opentelemetry-apisdk-with-elastic-apm-agents title: OpenTelemetry API/SDK with Elastic APM agents # description: Description to be written tags: [ 'serverless', 'observability', 'reference' ] --- -No source content found. + +
+ +Use the OpenTelemetry API/SDKs with Elastic APM agents. +Supported Elastic APM agents translate OpenTelemetry API calls to Elastic APM API calls. +This allows you to reuse your existing instrumentation to create Elastic APM transactions and spans. + + +If you'd like to use OpenTelemetry to send data directly to the APM server instead, +see OpenTelemetry native support. + + +See the relevant Elastic APM agent documentation to get started: + +* [Java](((apm-java-ref))/opentelemetry-bridge.html) +* .NET (link coming soon) + {/* * [.NET](((apm-dotnet-ref))/opentelemetry-bridge.html) */} + +* [Node.js](((apm-node-ref))/opentelemetry-bridge.html) +* [Python](((apm-py-ref))/opentelemetry-bridge.html) + +
+ +## Next steps + +* Collect metrics +* Add Resource attributes +* Learn about the limitations of this integration + diff --git a/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx b/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx index 97be9691e1..39675ed50e 100644 --- a/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx +++ b/docs/apm-agents-opentelemetry-opentelemetry-native-support.mdx @@ -1,9 +1,166 @@ --- -id: serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport +id: serverlessObservabilityApmAgentsOtelNativeSupport slug: /serverless/observability/apm-agents-opentelemetry-opentelemetry-native-support title: OpenTelemetry native support # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- -No source content found. + +
+ +The ((stack)) natively supports the OpenTelemetry protocol (OTLP). +This means trace data and metrics collected from your applications and infrastructure can +be sent directly to the ((stack)). + +* Send data to the ((stack)) from an OpenTelemetry collector +* Send data to the ((stack)) from an OpenTelemetry agent + +
+ +## Send data from an OpenTelemetry collector + +Connect your OpenTelemetry collector instances to Elastic ((observability)) using the OTLP exporter: + +```yaml +receivers: [^1] + # ... + otlp: + +processors: [^2] + # ... + memory_limiter: + check_interval: 1s + limit_mib: 2000 + batch: + +exporters: + logging: + loglevel: warn [^3] + otlp/elastic: [^4] + # Elastic APM server https endpoint without the "https://" prefix + endpoint: "${ELASTIC_APM_SERVER_ENDPOINT}" <5> [^7] + headers: + # Elastic APM Server secret token + Authorization: "Bearer ${ELASTIC_APM_SECRET_TOKEN}" <6> [^7] + +service: + pipelines: + traces: + receivers: [otlp] + exporters: [logging, otlp/elastic] + metrics: + receivers: [otlp] + exporters: [logging, otlp/elastic] + logs: [^8] + receivers: [otlp] + exporters: [logging, otlp/elastic] +``` +[^1]: The receivers, like the +[OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver), that forward data emitted by APM agents, or the [host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/hostmetricsreceiver). +[^2]: We recommend using the [Batch processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md) and the [memory limiter processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md). For more information, see [recommended processors](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/README.md#recommended-processors). +[^3]: The [logging exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/loggingexporter) is helpful for troubleshooting and supports various logging levels, like `debug`, `info`, `warn`, and `error`. +[^4]: Elastic ((observability)) endpoint configuration. +APM Server supports a ProtoBuf payload via both the OTLP protocol over gRPC transport [(OTLP/gRPC)]({ot_grpc}) +and the OTLP protocol over HTTP transport [(OTLP/HTTP)]({ot_http}). +To learn more about these exporters, see the OpenTelemetry Collector documentation: +[OTLP/HTTP Exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter) or +[OTLP/gRPC exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlpexporter). +[^5]: Hostname and port of the APM Server endpoint. For example, `elastic-apm-server:8200`. +[^6]: Credential for Elastic APM {/* secret token authorization (`Authorization: "Bearer a_secret_token"`) or API key authorization */} (`Authorization: "ApiKey an_api_key"`). +[^7]: Environment-specific configuration parameters can be conveniently passed in as environment variables documented [here](https://opentelemetry.io/docs/collector/configuration/#configuration-environment-variables) (e.g. `ELASTIC_APM_SERVER_ENDPOINT` and `ELASTIC_APM_SECRET_TOKEN`). +[^8]: To send OpenTelemetry logs to ((stack)) version 8.0+, declare a `logs` pipeline. + +You're now ready to export traces and metrics from your services and applications. + + +When using the OpenTelemetry collector, you should always prefer sending data via the [`OTLP` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter) to an Elastic APM Server. +Other methods, like using the [`elasticsearch` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/elasticsearchexporter) to send data directly to ((es)) will send data to the ((stack)), +but will bypass all of the validation and data processing that the APM Server performs. +In addition, your data will not be viewable in the ((kib)) ((observability)) apps if you use the `elasticsearch` exporter. + + +
+ +## Send data from an OpenTelemetry agent + +To export traces and metrics to APM Server, instrument your services and applications +with the OpenTelemetry API, SDK, or both. For example, if you are a Java developer, you need to instrument your Java app with the +[OpenTelemetry agent for Java](https://github.com/open-telemetry/opentelemetry-java-instrumentation). +See the [OpenTelemetry Instrumentation guides](https://opentelemetry.io/docs/instrumentation/) to download the +OpenTelemetry Agent or SDK for your language. + +Define the following environment variables to configure the OpenTelemetry agent and enable communication with Elastic APM. + +```bash +export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production +export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200 +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token" +export OTEL_METRICS_EXPORTER="otlp" \ +export OTEL_LOGS_EXPORTER="otlp" \ [^1] +java -javaagent:/path/to/opentelemetry-javaagent-all.jar \ + -classpath lib/*:classes/ \ + com.mycompany.checkout.CheckoutServiceServer +``` +[^1]: The OpenTelemetry logs intake via APM Server is currently in technical preview. + + + + `OTEL_RESOURCE_ATTRIBUTES` + Fields that describe the service and the environment that the service runs in. See resource attributes for more information. + + + `OTEL_EXPORTER_OTLP_ENDPOINT` + APM Server URL. The host and port that APM Server listens for events on. + + + `OTEL_EXPORTER_OTLP_HEADERS` + + Authorization header that includes the Elastic APM Secret token or API key: `"Authorization=Bearer an_apm_secret_token"` or `"Authorization=ApiKey an_api_key"`. + + For information on how to format an API key, see + [API keys](((apm-guide-ref))/api-key.html). + + + + `OTEL_EXPORTER_OTLP_CERTIFICATE` + The trusted certificate used to verify the TLS credentials of the client. (optional) + + + +You are now ready to collect traces and metrics before verifying metrics +and visualizing metrics in ((kib)). + +
+ +## Proxy requests to APM Server + +APM Server supports both the [(OTLP/gRPC)]({ot_grpc}) and [(OTLP/HTTP)]({ot_http}) protocol on the same port as Elastic APM agent requests. For ease of setup, we recommend using OTLP/HTTP when proxying or load balancing requests to the APM Server. + +If you use the OTLP/gRPC protocol, requests to the APM Server must use either HTTP/2 over TLS or HTTP/2 Cleartext (H2C). No matter which protocol is used, OTLP/gRPC requests will have the header: `"Content-Type: application/grpc"`. + +When using a layer 7 (L7) proxy like AWS ALB, requests must be proxied in a way that ensures requests to the APM Server follow the rules outlined above. For example, with ALB you can create rules to select an alternative backend protocol based on the headers of requests coming into ALB. In this example, you'd select the gRPC protocol when the `"Content-Type: application/grpc"` header exists on a request. + +For more information on how to configure an AWS ALB to support gRPC, see this AWS blog post: +[Application Load Balancer Support for End-to-End HTTP/2 and gRPC](https://aws.amazon.com/blogs/aws/new-application-load-balancer-support-for-end-to-end-http-2-and-grpc/). + +For more information on how APM Server services gRPC requests, see +[Muxing gRPC and HTTP/1.1](https://github.com/elastic/apm-server/blob/main/dev_docs/otel.md#muxing-grpc-and-http11). + +
+ +## Next steps + +* Collect metrics +* Add Resource attributes +* Learn about the limitations of this integration + diff --git a/docs/apm-agents-opentelemetry-other-execution-environments.mdx b/docs/apm-agents-opentelemetry-other-execution-environments.mdx index 6535ca144b..d381895c40 100644 --- a/docs/apm-agents-opentelemetry-other-execution-environments.mdx +++ b/docs/apm-agents-opentelemetry-other-execution-environments.mdx @@ -6,4 +6,187 @@ title: Other execution environments tags: [ 'serverless', 'observability', 'how-to' ] --- -No source content found. + +
+ + * AWS Lambda Support + * Instrumenting AWS Lambda Java functions with Terraform + * Instrumenting AWS Lambda Node.js functions + * Instrumenting AWS Lambda Node.js functions with Terraform + +
+ +## AWS Lambda Support + +AWS Lambda functions can be instrumented with OpenTelemetry and monitored with Elastic ((observability)). + +To get started, follow the official AWS Distro for OpenTelemetry Lambda [getting started documentation](https://aws-otel.github.io/docs/getting-started/lambda) and configure the OpenTelemetry Collector to output traces and metrics to your Elastic cluster. + +
+ +### Instrumenting AWS Lambda Java functions + + +For a better startup time, we recommend using SDK-based instrumentation, i.e. manual instrumentation of the code, rather than auto instrumentation. + + +To instrument AWS Lambda Java functions, follow the official [AWS Distro for OpenTelemetry Lambda Support For Java](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java). + +Noteworthy configuration elements: + +* AWS Lambda Java functions should extend `com.amazonaws.services.lambda.runtime.RequestHandler`, + + ```java + public class ExampleRequestHandler implements RequestHandler { + public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent event, Context context) { + // add your code ... + } + + ``` + +* When using SDK-based instrumentation, frameworks you want to gain visibility of should be manually instrumented + * The below example instruments [OkHttpClient](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/) with the OpenTelemetry instrument [io.opentelemetry.instrumentation:opentelemetry-okhttp-3.0:1.3.1-alpha](https://search.maven.org/artifact/io.opentelemetry.instrumentation/opentelemetry-okhttp-3.0/1.3.1-alpha/jar) + + ```java + import io.opentelemetry.instrumentation.okhttp.v3_0.OkHttpTracing; + + OkHttpClient httpClient = new OkHttpClient.Builder() + .addInterceptor(OkHttpTracing.create(GlobalOpenTelemetry.get()).newInterceptor()) + .build(); + ``` + +* The configuration of the OpenTelemetry Collector, with the definition of the Elastic ((observability)) endpoint, can be added to the root directory of the Lambda binaries (e.g. defined in `src/main/resources/opentelemetry-collector.yaml`) + + ```yaml + # Copy opentelemetry-collector.yaml in the root directory of the lambda function + # Set an environment variable 'OPENTELEMETRY_COLLECTOR_CONFIG_FILE' to '/var/task/opentelemetry-collector.yaml' + receivers: + otlp: + protocols: + http: + grpc: + + exporters: + logging: + loglevel: debug + otlp/elastic: + # Elastic APM server https endpoint without the "https://" prefix + endpoint: "${ELASTIC_OTLP_ENDPOINT}" [^1] + headers: + # Elastic APM Server secret token + Authorization: "Bearer ${ELASTIC_OTLP_TOKEN}" [^1] + + service: + pipelines: + traces: + receivers: [otlp] + exporters: [logging, otlp/elastic] + metrics: + receivers: [otlp] + exporters: [logging, otlp/elastic] + logs: + receivers: [otlp] + exporters: [logging, otlp/elastic] + ``` + [^1]: Environment-specific configuration parameters can be conveniently passed in as environment variables: `ELASTIC_OTLP_ENDPOINT` and `ELASTIC_OTLP_TOKEN` + +* Configure the AWS Lambda Java function with: + * [Function + layer](https://docs.aws.amazon.com/lambda/latest/dg/API_Layer.html): The latest [AWS + Lambda layer for OpenTelemetry](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java) (e.g. `arn:aws:lambda:eu-west-1:901920570463:layer:aws-otel-java-wrapper-ver-1-2-0:1`) + + * [`TracingConfig` / Mode](https://docs.aws.amazon.com/lambda/latest/dg/API_TracingConfig.html) set to `PassTrough` + * [`FunctionConfiguration` / Timeout](https://docs.aws.amazon.com/lambda/latest/dg/API_FunctionConfiguration.html) set to more than 10 seconds to support the longer cold start inherent to the Lambda Java Runtime + * Export the environment variables: + * `AWS_LAMBDA_EXEC_WRAPPER="/opt/otel-proxy-handler"` for wrapping handlers proxied through the API Gateway (see [here](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java#enable-auto-instrumentation-for-your-lambda-function)) + * `OTEL_PROPAGATORS="tracecontext, baggage"` to override the default setting that also enables X-Ray headers causing interferences between OpenTelemetry and X-Ray + * `OPENTELEMETRY_COLLECTOR_CONFIG_FILE="/var/task/opentelemetry-collector.yaml"` to specify the path to your OpenTelemetry Collector configuration + +
+ +### Instrumenting AWS Lambda Java functions with Terraform + +We recommend using an infrastructure as code solution like Terraform or Ansible to manage the configuration of your AWS Lambda functions. + +Here is an example of AWS Lambda Java function managed with Terraform and the [AWS Provider / Lambda Functions](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function): + +* Sample Terraform code: https://github.com/cyrille-leclerc/my-serverless-shopping-cart/tree/main/checkout-function/deploy +* Note that the Terraform code to manage the HTTP API Gateway ([here](https://github.com/cyrille-leclerc/my-serverless-shopping-cart/tree/main/utils/terraform/api-gateway-proxy)) is copied from the official OpenTelemetry Lambda sample [here](https://github.com/open-telemetry/opentelemetry-lambda/tree/e72467a085a2a6e57af133032f85ac5b8bbbb8d1/utils) + +
+ +### Instrumenting AWS Lambda Node.js functions + + +For a better startup time, we recommend using SDK-based instrumentation for manual instrumentation of the code rather than auto instrumentation. + + +To instrument AWS Lambda Node.js functions, see [AWS Distro for OpenTelemetry Lambda Support For JavaScript](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js). + +The configuration of the OpenTelemetry Collector, with the definition of the Elastic ((observability)) endpoint, can be added to the root directory of the Lambda binaries: `src/main/resources/opentelemetry-collector.yaml`. + +```yaml +# Copy opentelemetry-collector.yaml in the root directory of the lambda function +# Set an environment variable 'OPENTELEMETRY_COLLECTOR_CONFIG_FILE' to '/var/task/opentelemetry-collector.yaml' +receivers: + otlp: + protocols: + http: + grpc: + +exporters: + logging: + loglevel: debug + otlp/elastic: + # Elastic APM server https endpoint without the "https://" prefix + endpoint: "${ELASTIC_OTLP_ENDPOINT}" [^1] + headers: + # Elastic APM Server secret token + Authorization: "Bearer ${ELASTIC_OTLP_TOKEN}" [^1] + +service: + pipelines: + traces: + receivers: [otlp] + exporters: [logging, otlp/elastic] + metrics: + receivers: [otlp] + exporters: [logging, otlp/elastic] + logs: + receivers: [otlp] + exporters: [logging, otlp/elastic] +``` +[^1]: Environment-specific configuration parameters can be conveniently passed in as environment variables: `ELASTIC_OTLP_ENDPOINT` and `ELASTIC_OTLP_TOKEN` + +Configure the AWS Lambda Node.js function: + +* [Function + layer](https://docs.aws.amazon.com/lambda/latest/dg/API_Layer.html): The latest [AWS + Lambda layer for OpenTelemetry](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js). For example, `arn:aws:lambda:eu-west-1:901920570463:layer:aws-otel-nodejs-ver-0-23-0:1`) + +* [`TracingConfig` / Mode](https://docs.aws.amazon.com/lambda/latest/dg/API_TracingConfig.html) set to `PassTrough` +* [`FunctionConfiguration` / Timeout](https://docs.aws.amazon.com/lambda/latest/dg/API_FunctionConfiguration.html) set to more than 10 seconds to support the cold start of the Lambda JavaScript Runtime +* Export the environment variables: + * `AWS_LAMBDA_EXEC_WRAPPER="/opt/otel-handler"` for wrapping handlers proxied through the API Gateway. See [enable auto instrumentation for your lambda-function](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js#enable-auto-instrumentation-for-your-lambda-function). + * `OTEL_PROPAGATORS="tracecontext"` to override the default setting that also enables X-Ray headers causing interferences between OpenTelemetry and X-Ray + * `OPENTELEMETRY_COLLECTOR_CONFIG_FILE="/var/task/opentelemetry-collector.yaml"` to specify the path to your OpenTelemetry Collector configuration. + * `OTEL_TRACES_SAMPLER="AlwaysOn"` define the required sampler strategy if it is not sent from the caller. Note that `Always_on` can potentially create a very large amount of data, so in production set the correct sampling configuration, as per the [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampling). + +
+ +### Instrumenting AWS Lambda Node.js functions with Terraform + +To manage the configuration of your AWS Lambda functions, we recommend using an infrastructure as code solution like Terraform or Ansible. + +Here is an example of AWS Lambda Node.js function managed with Terraform and the [AWS Provider / Lambda Functions](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function): + +* [Sample Terraform code](https://github.com/michaelhyatt/terraform-aws-nodejs-api-worker-otel/tree/v0.24) + +
+ +### Next steps + +* Collect metrics +* Add Resource attributes +* Learn about the limitations of this integration + diff --git a/docs/apm-agents-opentelemetry-resource-attributes.mdx b/docs/apm-agents-opentelemetry-resource-attributes.mdx index f107d520ae..7c07cf0596 100644 --- a/docs/apm-agents-opentelemetry-resource-attributes.mdx +++ b/docs/apm-agents-opentelemetry-resource-attributes.mdx @@ -6,4 +6,44 @@ title: Resource attributes tags: [ 'serverless', 'observability', 'how-to' ] --- -No source content found. + +
+ +A resource attribute is a key/value pair containing information about the entity producing telemetry. +Resource attributes are mapped to Elastic Common Schema (ECS) fields like `service.*`, `cloud.*`, `process.*`, etc. +These fields describe the service and the environment that the service runs in. + +The examples below set the Elastic (ECS) `service.environment` field for the resource, i.e. service, that is producing trace events. +Note that Elastic maps the OpenTelemetry `deployment.environment` field to +the ECS `service.environment` field on ingestion. + +**OpenTelemetry agent** + +Use the `OTEL_RESOURCE_ATTRIBUTES` environment variable to pass resource attributes at process invocation. + +```bash +export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production +``` + +**OpenTelemetry collector** + +Use the [resource processor]({ot_resource}) to set or apply changes to resource attributes. + +```yaml +... +processors: + resource: + attributes: + - key: deployment.environment + action: insert + value: production +... +``` + + + +Need to add event attributes instead? +Use attributes--not to be confused with resource attributes--to add data to span, log, or metric events. +Attributes can be added as a part of the OpenTelemetry instrumentation process or with the [attributes processor]({ot_attr}). + + \ No newline at end of file diff --git a/docs/apm-agents-opentelemetry.mdx b/docs/apm-agents-opentelemetry.mdx index 540eaa0c82..e5c475c87d 100644 --- a/docs/apm-agents-opentelemetry.mdx +++ b/docs/apm-agents-opentelemetry.mdx @@ -6,4 +6,95 @@ title: OpenTelemetry tags: [ 'serverless', 'observability', 'overview' ] --- -No source content found. + +{/* import DiagramsApmOtelArchitecture from './transclusion/diagrams/apm-otel-architecture.mdx' */} +{/* import Snippet1 from './transclusion/open-telemetry/otel-get-started.mdx' */} + +
+ +export let ot_what = "https://opentelemetry.io/docs/concepts/what-is-opentelemetry/" + +export let ot_spec = "https://github.com/open-telemetry/opentelemetry-specification/blob/master/README.md" + +export let ot_grpc = "https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#otlpgrpc" + +export let ot_http = "https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#otlphttp" + +export let ot_contrib = "https://github.com/open-telemetry/opentelemetry-collector-contrib" + +export let ot_resource = "{ot_contrib}/tree/main/processor/resourceprocessor" + +export let ot_attr = "{ot_contrib}/blob/main/processor/attributesprocessor" + +export let ot_repo = "https://github.com/open-telemetry/opentelemetry-collector" + +export let ot_pipelines = "https://opentelemetry.io/docs/collector/configuration/#service" + +export let ot_extension = "{ot_repo}/blob/master/extension/README.md" + +export let ot_scaling = "{ot_repo}/blob/master/docs/performance.md" + +export let ot_collector = "https://opentelemetry.io/docs/collector/getting-started/" + +export let ot_dockerhub = "https://hub.docker.com/r/otel/opentelemetry-collector-contrib" + +[OpenTelemetry]({ot_what}) is a set of APIs, SDKs, tooling, and integrations that enable the capture and management of +telemetry data from your services and applications. For more information about the +OpenTelemetry project, see the [spec]({ot_spec}). + +## OpenTelemetry and the ((stack)) + +{/* */} + +Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation +to easily send observability data to the ((stack)). +There are four ways to integrate OpenTelemetry with the ((stack)): + +**OpenTelemetry API/SDK with Elastic APM agents** + +To unlock the full power of the ((stack)), use the OpenTelemetry API/SDKs with Elastic APM agents, +currently supported by the Java, Python, .NET, and Node.js agents. +These Elastic APM agents translate OpenTelemetry API calls to Elastic APM API calls. +This allows you to reuse your existing instrumentation to create Elastic APM transactions and spans-- +avoiding vendor lock-in and having to redo manual instrumentation. + +Get started. + +**OpenTelemetry agent** + +The ((stack)) natively supports the OpenTelemetry protocol (OTLP). +This means trace data and metrics collected from your applications and infrastructure by an +OpenTelemetry agent can be sent directly to the ((stack)). + +Get started. + +**OpenTelemetry collector** + +The ((stack)) natively supports the OpenTelemetry protocol (OTLP). +This means trace data and metrics collected from your applications and infrastructure by an +OpenTelemetry collector can be sent directly to the ((stack)). + +Get started. + +**Lambda collector exporter** + +AWS Lambda functions can be instrumented with OpenTelemetry and monitored with Elastic ((observability)). + +Get started. + +{/* The include that was here is another page */} + +{/* The include that was here is another page */} + +{/* The include that was here is another page */} + +{/* The include that was here is another page */} + +{/* The include that was here is another page */} + +{/* The include that was here is another page */} + +{/* **** */} +{/* The text below is used in the Quick start guide */} +{/* */} +{/* **** */} \ No newline at end of file diff --git a/docs/monitor-application-performance-apm.mdx b/docs/monitor-application-performance-apm.mdx index 3f6221041e..f552a78fda 100644 --- a/docs/monitor-application-performance-apm.mdx +++ b/docs/monitor-application-performance-apm.mdx @@ -5,3 +5,25 @@ title: Monitor application performance (APM) # description: Description to be written tags: [ 'serverless', 'observability', 'overview' ] --- + + +
+ +Elastic APM is an application performance monitoring system built on the ((stack)). +It allows you to monitor software services and applications in real-time, by +collecting detailed performance information on response time for incoming requests, +database queries, calls to caches, external HTTP requests, and more. +This makes it easy to pinpoint and fix performance problems quickly. + +Elastic APM also automatically collects unhandled errors and exceptions. +Errors are grouped based primarily on the stack trace, +so you can identify new errors as they appear and keep an eye on how many times specific errors happen. + +Metrics are another vital source of information when debugging production systems. +Elastic APM agents automatically pick up basic host-level metrics and agent-specific metrics, +like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent. + +## Give Elastic APM a try + +Use the {/* Quick start with ((ecloud)) */} to quickly spin up an APM deployment. +Want to host everything yourself instead? See {/* Self manage APM Server */}. diff --git a/serverless-observability.docnav.json b/serverless-observability.docnav.json index fef14369db..d652e1971c 100644 --- a/serverless-observability.docnav.json +++ b/serverless-observability.docnav.json @@ -66,6 +66,7 @@ }, { "id": "serverlessObservabilityMonitorApplicationPerformanceApmSendTracesToElastic", + "classic-sources": [ "enObservabilityIngestTraces" ], "items": [ { "id": "serverlessObservabilityApmAgents" @@ -479,30 +480,31 @@ }, { "id": "serverlessObservabilityApmAgentsOtel", + "classic-sources": [ "enApmGuideOpenTelemetry" ], "items": [ { - "id": "serverlessObservabilityApmAgentsOtelOpentelemetryApisdkWithElasticApmAgents", - "classic-sources": [] + "id": "serverlessObservabilityApmAgentsOtelApisdkWithElasticApmAgents", + "classic-sources": [ "enApmGuideOpenTelemetryWithElastic" ] }, { - "id": "serverlessObservabilityApmAgentsOtelOpentelemetryNativeSupport", - "classic-sources": [] + "id": "serverlessObservabilityApmAgentsOtelNativeSupport", + "classic-sources": [ "enApmGuideOpenTelemetryDirect" ] }, { "id": "serverlessObservabilityApmAgentsOtelOtherExecutionEnvironments", - "classic-sources": [] + "classic-sources": [ "enApmGuideOpenTelemetryOtherEnv" ] }, { "id": "serverlessObservabilityApmAgentsOtelCollectMetrics", - "classic-sources": [] + "classic-sources": [ "enApmGuideOpenTelemetryCollectMetrics" ] }, { "id": "serverlessObservabilityApmAgentsOtelLimitations", - "classic-sources": [] + "classic-sources": [ "enApmGuideOpenTelemetryKnownLimitations" ] }, { "id": "serverlessObservabilityApmAgentsOtelResourceAttributes", - "classic-sources": [] + "classic-sources": [ "enApmGuideOpenTelemetryResourceAttributes" ] } ] },