diff --git a/docs/getting-started-apm-server.asciidoc b/docs/getting-started-apm-server.asciidoc index 83e47e45d2b..f737d232034 100644 --- a/docs/getting-started-apm-server.asciidoc +++ b/docs/getting-started-apm-server.asciidoc @@ -352,11 +352,12 @@ If you haven't already, you can now install APM Agents in your services! * {apm-java-ref-v}/intro.html[Java agent] * {apm-dotnet-ref-v}/intro.html[.NET agent] * {apm-node-ref-v}/intro.html[Node.js agent] +* {apm-php-ref-v}/intro.html[PHP agent] * {apm-py-ref-v}/getting-started.html[Python agent] * {apm-ruby-ref-v}/introduction.html[Ruby agent] * {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] -Once you have at least one Agent sending data to APM Server, +Once you have at least one APM agent sending data to APM Server, you can start visualizing your data in the {kibana-ref}/xpack-apm.html[APM app]. If you're migrating from Jaeger, see <>. diff --git a/docs/guide/agent-server-compatibility.asciidoc b/docs/guide/agent-server-compatibility.asciidoc index 5c73fe14cd2..a3e59d1dce4 100644 --- a/docs/guide/agent-server-compatibility.asciidoc +++ b/docs/guide/agent-server-compatibility.asciidoc @@ -5,39 +5,43 @@ The chart below outlines the compatibility between different versions of the APM [options="header"] |==== -|Agent |Agent Version |APM Server Version +|Agent |Agent version |APM Server version // Go -.1+|**Go Agent** +.1+|**Go agent** |`1.x` |≥ `6.5` // Java -.1+|**Java Agent** +.1+|**Java agent** |`1.x`|≥ `6.5` // .NET -.1+|**.NET Agent** +.1+|**.NET agent** |`1.x` |≥ `6.5` // Node -.3+|**Node.js Agent** +.3+|**Node.js agent** |`1.x` |`6.2`-`6.x` |`2.x` |≥ `6.5` |`3.x` |≥ `6.6` +// PHP +.1+|**PHP agent** +|`1.x` |≥ `7.0` + // Python -.3+|**Python Agent** +.3+|**Python agent** |`2.x`, `3.x` |`6.2`-`6.x` |`4.x` |≥ `6.5` |`5.x` |≥ `6.6` // Ruby -.3+|**Ruby Agent** +.3+|**Ruby agent** |`1.x` |`6.4`-`6.x` |`2.x` |≥ `6.5` |`3.x` |≥ `6.5` // RUM -.4+|**JavaScript RUM Agent** +.4+|**JavaScript RUM agent** |`0.x` |`6.3`-`6.4` |`1.x` |`6.4` |`2.x`, `3.x`, `4.x` |≥ `6.5` diff --git a/docs/guide/apm-data-model.asciidoc b/docs/guide/apm-data-model.asciidoc index 589f6f45683..2744943b78f 100644 --- a/docs/guide/apm-data-model.asciidoc +++ b/docs/guide/apm-data-model.asciidoc @@ -53,6 +53,7 @@ To configure the number of spans recorded per transaction, see the relevant Agen * Java: {apm-java-ref-v}/config-core.html#config-transaction-max-spans[`transaction_max_spans`] * .NET: {apm-dotnet-ref-v}/config-core.html#config-transaction-max-spans[`TransactionMaxSpans`] * Node.js: {apm-node-ref-v}/configuration.html#transaction-max-spans[`transactionMaxSpans`] +* PHP: {apm-php-ref-v}/configuration-reference.html#config-transaction-max-spans[`transaction_max_spans`] * Python: {apm-py-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] * Ruby: {apm-ruby-ref-v}/configuration.html#config-transaction-max-spans[`transaction_max_spans`] @@ -206,9 +207,10 @@ Defining too many unique fields in an index is a condition that can lead to a ===== Agent API reference * Go: {apm-go-ref-v}/api.html#context-set-label[`SetLabel`] -* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-tag[`addLabel`] +* Java: {apm-java-ref-v}/public-api.html#api-transaction-add-tag[`setLabel`] * .NET: {apm-dotnet-ref-v}/public-api.html#api-transaction-tags[`Labels`] * Node.js: {apm-node-ref-v}/agent-api.html#apm-set-label[`setLabel`] | {apm-node-ref-v}/agent-api.html#apm-add-labels[`addLabels`] +* PHP: {apm-php-ref}/public-api.html#api-transaction-interface-set-label[`Transaction` `setLabel`] | {apm-php-ref}/public-api.html#api-span-interface-set-label[`Span` `setLabel`] * Python: {apm-py-ref-v}/api.html#api-label[`elasticapm.label()`] * Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-label[`set_label`] * Rum: {apm-rum-ref-v}/agent-api.html#apm-add-labels[`addLabels`] @@ -241,6 +243,7 @@ IMPORTANT: Setting a circular object, a large object, or a non JSON serializable * Java: {apm-java-ref-v}/public-api.html#api-transaction-add-custom-context[`addCustomContext`] * .NET: _coming soon_ * Node.js: {apm-node-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] +* PHP: _coming soon_ * Python: {apm-py-ref-v}/api.html#api-set-custom-context[`set_custom_context`] * Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-custom-context[`set_custom_context`] * Rum: {apm-rum-ref-v}/agent-api.html#apm-set-custom-context[`setCustomContext`] @@ -265,6 +268,7 @@ Indexed means the data is searchable and aggregatable in Elasticsearch. * Java: {apm-java-ref-v}/public-api.html#api-transaction-set-user[`setUser`] * .NET _coming soon_ * Node.js: {apm-node-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] +* PHP: _coming soon_ * Python: {apm-py-ref-v}/api.html#api-set-user-context[`set_user_context`] * Ruby: {apm-ruby-ref-v}/api.html#api-agent-set-user[`set_user`] * Rum: {apm-rum-ref-v}/agent-api.html#apm-set-user-context[`setUserContext`] diff --git a/docs/guide/apm-doc-directory.asciidoc b/docs/guide/apm-doc-directory.asciidoc index 43b983cfd01..8bd54eeef4b 100644 --- a/docs/guide/apm-doc-directory.asciidoc +++ b/docs/guide/apm-doc-directory.asciidoc @@ -20,8 +20,7 @@ Each agent has its own documentation: * {apm-java-ref-v}/intro.html[Java agent] * {apm-dotnet-ref-v}/intro.html[.NET agent] * {apm-node-ref-v}/intro.html[Node.js agent] -// Uncomment PHP Agent when ready -// * {apm-php-ref}/intro.html[PHP agent] +* {apm-php-ref-v}/intro.html[PHP agent] * {apm-py-ref-v}/getting-started.html[Python agent] * {apm-ruby-ref-v}/introduction.html[Ruby agent] * {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent] diff --git a/docs/guide/distributed-tracing.asciidoc b/docs/guide/distributed-tracing.asciidoc index d84bd420e0a..15e44200dec 100644 --- a/docs/guide/distributed-tracing.asciidoc +++ b/docs/guide/distributed-tracing.asciidoc @@ -103,7 +103,7 @@ include::../tab-widgets/distributed-trace-send-widget.asciidoc[] -- [float] -==== Add the `traceparent` header to incoming requests +==== Parse the `traceparent` header on incoming requests Receiving services must parse the incoming `traceparent` header, and start a new transaction or span as a child of the received context. diff --git a/docs/guide/opentracing.asciidoc b/docs/guide/opentracing.asciidoc index d87f5baed56..cffdd66001c 100644 --- a/docs/guide/opentracing.asciidoc +++ b/docs/guide/opentracing.asciidoc @@ -16,4 +16,4 @@ Not all features of the OpenTracing API are supported. In addition, there are so * {apm-node-ref-v}/opentracing.html[Node.js agent] * {apm-py-ref-v}/opentracing-bridge.html[Python agent] * {apm-ruby-ref-v}/opentracing.html[Ruby agent] -* {apm-rum-ref-v}/opentracing.html[JavaScript Real User Monitoring (RUM) agent] \ No newline at end of file +* {apm-rum-ref-v}/opentracing.html[JavaScript Real User Monitoring (RUM) agent] diff --git a/docs/guide/trace-sampling.asciidoc b/docs/guide/trace-sampling.asciidoc index 1637b1a1bd6..7d640eb1a7c 100644 --- a/docs/guide/trace-sampling.asciidoc +++ b/docs/guide/trace-sampling.asciidoc @@ -103,5 +103,6 @@ See the relevant agent's documentation for more details: * Java: {apm-java-ref-v}/config-core.html#config-transaction-sample-rate[`transaction_sample_rate`] * .NET: {apm-dotnet-ref-v}/config-core.html#config-transaction-sample-rate[`TransactionSampleRate`] * Node.js: {apm-node-ref-v}/configuration.html#transaction-sample-rate[`transactionSampleRate`] +* PHP: {apm-php-ref-v}/configuration-reference.html#config-transaction-sample-rate[`transaction_sample_rate`] * Python: {apm-py-ref-v}/configuration.html#config-transaction-sample-rate[`transaction_sample_rate`] * Ruby: {apm-ruby-ref-v}/configuration.html#config-transaction-sample-rate[`transaction_sample_rate`] \ No newline at end of file diff --git a/docs/guide/troubleshooting.asciidoc b/docs/guide/troubleshooting.asciidoc index f27b2694ba6..ede02b333f6 100644 --- a/docs/guide/troubleshooting.asciidoc +++ b/docs/guide/troubleshooting.asciidoc @@ -14,6 +14,7 @@ The APM Server, APM app, and each APM agent has a troubleshooting guide: * {apm-go-ref-v}/troubleshooting.html[Go agent troubleshooting] * {apm-java-ref-v}/trouble-shooting.html[Java agent troubleshooting] * {apm-node-ref-v}/troubleshooting.html[Node.js agent troubleshooting] +* {apm-php-ref-v}/troubleshooting.html[PHP agent troubleshooting] * {apm-py-ref-v}/troubleshooting.html[Python agent troubleshooting] * {apm-ruby-ref-v}/debugging.html[Ruby agent troubleshooting] * {apm-rum-ref-v}/troubleshooting.html[RUM troubleshooting] diff --git a/docs/secure-communication-agents.asciidoc b/docs/secure-communication-agents.asciidoc index ad064caa8ac..a2782330526 100644 --- a/docs/secure-communication-agents.asciidoc +++ b/docs/secure-communication-agents.asciidoc @@ -1,5 +1,5 @@ [[secure-communication-agents]] -== Secure communication with APM Agents +== Secure communication with APM agents Communication between APM agents and APM Server can be both encrypted and authenticated. Encryption is achievable through <>. @@ -279,18 +279,18 @@ Authorized for privilege "sourcemap:write"...: Yes [[set-api-key]] [float] -=== Set the API key in your APM Agents +=== Set the API key in your APM agents -You can now apply your newly created API keys in the configuration of each of your APM Agents. -See the relevant Agent documentation for additional information: +You can now apply your newly created API keys in the configuration of each of your APM agents. +See the relevant agent documentation for additional information: -* *Go Agent*: {apm-go-ref}/configuration.html#config-api-key[`ELASTIC_APM_API_KEY`] -* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-api-key[`ApiKey`] -* *Java Agent*: {apm-java-ref}/config-reporter.html#config-api-key[`api_key`] -* *Python Agent*: {apm-py-ref}/configuration.html#config-api-key[`api_key`] -* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-api-key[`api_key`] -// No issue or docs yet -// * *Node.js Agent*: {apm-node-ref}/configuration.html[`api_key`] +* *Go agent*: {apm-go-ref}/configuration.html#config-api-key[`ELASTIC_APM_API_KEY`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-api-key[`ApiKey`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-api-key[`api_key`] +* *Node.js agent*: {apm-node-ref}/configuration.html#api-key[`apiKey`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-api-key[`api_key`] +* *Python agent*: {apm-py-ref}/configuration.html#config-api-key[`api_key`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-api-key[`api_key`] [[api-key-settings]] === `api_key.*` configuration options @@ -436,11 +436,11 @@ Both the agents and the APM servers have to be configured with the same secret t NOTE: Secret tokens are sent as plain-text, so they only provide security when used in combination with <>. -To secure the communication between APM Agents and the APM Server with a secret token: +To secure the communication between APM agents and the APM Server with a secret token: . Make sure <> is enabled -. <> -. <> +. <> +. <> NOTE: Secret tokens are not applicable for the RUM Agent, as there is no way to prevent them from being publicly exposed. @@ -460,43 +460,52 @@ apm-server.secret_token: We recommend saving the token in the APM Server <>. -IMPORTANT: Secret tokens are not applicable for the RUM Agent, +IMPORTANT: Secret tokens are not applicable for the RUM agent, as there is no way to prevent them from being publicly exposed. **Agent specific configuration** Each Agent has a configuration for setting the value of the secret token: -* *Go Agent*: {apm-go-ref}/configuration.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`] -* *Java Agent*: {apm-java-ref}/config-reporter.html#config-secret-token[`secret_token`] -* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`] -* *Node.js Agent*: {apm-node-ref}/configuration.html#secret-token[`Secret Token`] -* *Python Agent*: {apm-py-ref}/configuration.html#config-secret-token[`secret_token`] -* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-secret-token[`secret_token`] +* *Go agent*: {apm-go-ref}/configuration.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-secret-token[`secret_token`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`] +* *Node.js agent*: {apm-node-ref}/configuration.html#secret-token[`Secret Token`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-secret-token[`secret_token`] +* *Python agent*: {apm-py-ref}/configuration.html#config-secret-token[`secret_token`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-secret-token[`secret_token`] [[https-in-agents]] [float] -=== HTTPS communication in APM Agents +=== HTTPS communication in APM agents -To enable secure communication in your Agents, you need to update the configured server URL to use `HTTPS` instead of `HTTP`. +To enable secure communication in your agents, you need to update the configured server URL to use `HTTPS` instead of `HTTP`. -* *Go Agent*: {apm-go-ref}/configuration.html#config-server-url[`ELASTIC_APM_SERVER_URL`] -* *Java Agent*: {apm-java-ref}/config-reporter.html#config-server-urls[`server_urls`] -* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-server-url[`ServerUrl`] -* *Node.js Agent*: {apm-node-ref}/configuration.html#server-url[`serverUrl`] -* *Python Agent*: {apm-py-ref}/[`server_url`] -* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-server-url[`server_url`] +* *Go agent*: {apm-go-ref}/configuration.html#config-server-url[`ELASTIC_APM_SERVER_URL`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-server-urls[`server_urls`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-server-url[`ServerUrl`] +* *Node.js agent*: {apm-node-ref}/configuration.html#server-url[`serverUrl`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-server-url[`server_url`] +* *Python agent*: {apm-py-ref}/[`server_url`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-server-url[`server_url`] -Some Agents also allow you to specify a custom certificate authority for connecting to APM Server. +Some agents also allow you to specify a custom certificate authority for connecting to APM Server. -* *Go Agent*: {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] -* *Python Agent*: {apm-py-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] -* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-ssl-ca-cert[`server_ca_certedit`] +* *Go agent*: certificate pinning through {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] +* *Python agent*: certificate pinning through {apm-py-ref}/configuration.html#config-server-cert[`server_cert`] +* *Ruby agent*: certificate pinning through {apm-ruby-ref}/configuration.html#config-ssl-ca-cert[`server_ca_cert`] +* *NodeJS agent*: custom CA setting through {apm-node-ref}/configuration.html#server-ca-cert-file[`serverCaCertFile`] +* *Java agent*: adding the certificate to the JVM `trustStore`. +See {apm-java-ref}/ssl-configuration.html#ssl-server-authentication[APM Server authentication] for more details. -Most Agents that don't allow you specify a custom certificate will allow you to +Agents that don't allow you specify a custom certificate will allow you to disable verification of the SSL certificate. This ensures encryption, but does not verify that you are sending data to the correct APM Server. -* *Java Agent*: {apm-java-ref}/config-reporter.html#config-verify-server-cert[`verify_server_cert`] -* *Node.js Agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`] -* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-verify-server-cert[`VerifyServerCert`] +* *Go agent*: {apm-go-ref}/configuration.html#config-verify-server-cert[`ELASTIC_APM_VERIFY_SERVER_CERT`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-verify-server-cert[`VerifyServerCert`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-verify-server-cert[`verify_server_cert`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-verify-server-cert[`verify_server_cert`] +* *Python agent*: {apm-py-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] +* *NodeJS agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`] diff --git a/docs/ssl-input.asciidoc b/docs/ssl-input.asciidoc index 1f2eb28f2ba..46f16137569 100644 --- a/docs/ssl-input.asciidoc +++ b/docs/ssl-input.asciidoc @@ -40,22 +40,23 @@ of the APM Server by authenticating its certificate. When the APM server uses a certificate that is not chained to a publicly-trusted certificate (e.g. self-signed), additional setting will be required on the agent side: -* *Go Agent*: certificate pinning through {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] -* *Python Agent*: certificate pinning through {apm-py-ref}/configuration.html#config-server-cert[`server_cert`] -* *Ruby Agent*: certificate pinning through {apm-ruby-ref}/configuration.html#config-ssl-ca-cert[`server_ca_cert`] -* *NodeJS Agent*: custom CA setting through {apm-node-ref}/configuration.html#server-ca-cert-file[`serverCaCertFile`] -* *Java Agent*: adding the certificate to the JVM `trustStore`. +* *Go agent*: certificate pinning through {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`] +* *Python agent*: certificate pinning through {apm-py-ref}/configuration.html#config-server-cert[`server_cert`] +* *Ruby agent*: certificate pinning through {apm-ruby-ref}/configuration.html#config-ssl-ca-cert[`server_ca_cert`] +* *NodeJS agent*: custom CA setting through {apm-node-ref}/configuration.html#server-ca-cert-file[`serverCaCertFile`] +* *Java agent*: adding the certificate to the JVM `trustStore`. See {apm-java-ref}/ssl-configuration.html#ssl-server-authentication[APM Server authentication] for more details. It is not recommended to disable APM Server authentication, however it is possible through agents configuration: -* *Go Agent*: {apm-go-ref}/configuration.html#config-verify-server-cert[`ELASTIC_APM_VERIFY_SERVER_CERT`] -* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-verify-server-cert[`VerifyServerCert`] -* *Java Agent*: {apm-java-ref}/config-reporter.html#config-verify-server-cert[`verify_server_cert`] -* *Python Agent*: {apm-py-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] -* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] -* *NodeJS Agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`] +* *Go agent*: {apm-go-ref}/configuration.html#config-verify-server-cert[`ELASTIC_APM_VERIFY_SERVER_CERT`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-verify-server-cert[`VerifyServerCert`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-verify-server-cert[`verify_server_cert`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-verify-server-cert[`verify_server_cert`] +* *Python agent*: {apm-py-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-verify-server-cert[`verify_server_cert`] +* *NodeJS agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`] [[ssl-client-authentication]] ==== Client certificate authentication diff --git a/docs/tab-widgets/distributed-trace-receive-widget.asciidoc b/docs/tab-widgets/distributed-trace-receive-widget.asciidoc index 89c525c3ae0..80238d3f4ae 100644 --- a/docs/tab-widgets/distributed-trace-receive-widget.asciidoc +++ b/docs/tab-widgets/distributed-trace-receive-widget.asciidoc @@ -30,6 +30,13 @@ tabindex="-1"> Node.js + + +