Enhance service correlation doc

docs/en/observability/application-logs.asciidoc

@@ -36,7 +36,10 @@ For example, the same example shown above might look like this when structured w
 [[log-correlation]]
 == Log correlation
 
-To correlate your logs, you must annotate your logs with the APM identifier, `service.name`.
+Log correlation works at two levels:
+- at service level: annotation with `service.name`, `service.version` and `service.environment` allow to link logs with APM services
+- at trace level: annotation with `trace.id` and `transaction.id` allow to link logs with traces
+
 Elastic APM integrates with the most popular logging frameworks in each programming language to accomplish this automatically.
 
 // tag::correlate-logs[]

docs/en/observability/tab-widgets/filebeat-logs/content.asciidoc

@@ -19,6 +19,8 @@ filebeat.inputs:
       expand_keys: true <4>
   fields:
     service.name: your_service_name <5>
+    service.version: your_service_version <5>
+    service.environment: your_service_environment <5>
 
 processors: <6>
   - add_host_metadata: ~
@@ -30,7 +32,7 @@ processors: <6>
 <2> Values from the decoded JSON object overwrite the fields that {filebeat} normally adds (type, source, offset, etc.) in case of conflicts.
 <3> {filebeat} adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors.
 <4> {filebeat} will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure.
-<5> The `service.name` of the service you're collecting logs from. This is required for <<log-correlation>>.
+<5> The `service.name` (required), `service.version` (optional) and `service.environment` (optional) of the service you're collecting logs from, used for <<log-correlation>>.
 <6> Processors enhance your data. See {filebeat-ref}/filtering-and-enhancing-data.html[processors] to learn more.
 endif::ecs-logs[]
 ifdef::plaintext[]
@@ -102,4 +104,4 @@ labels:
 endif::ecs-logs[]
 ifdef::plaintext[]
 endif::plaintext[]
-// end::docker[]
+// end::docker[]

docs/en/shared/install-apm-agents/content.asciidoc

@@ -13,13 +13,21 @@ go get go.elastic.co/apm
 Agents are libraries that run inside of your application process.
 APM services are created programmatically based on the executable file name, or the `ELASTIC_APM_SERVICE_NAME` environment variable.
 
+Setting the service version with `ELASTIC_APM_SERVICE_VERSION` and environment with `ELASTIC_APM_ENVIRONMENT` is optional but recommended.
+
 [source,go]
 ----
 # Initialize using environment variables:
 
 # Set the service name. Allowed characters: # a-z, A-Z, 0-9, -, _, and space.
 # If ELASTIC_APM_SERVICE_NAME is not specified, the executable name will be used.
-export ELASTIC_APM_SERVICE_NAME=
+export ELASTIC_APM_SERVICE_NAME=my-application
+
+# Set the service version (optional but recommended)
+export ELASTIC_APM_SERVICE_VERSION=1.0
+
+# Set the environment (optional but recommended)
+export ELASTIC_APM_ENVIRONMENT=production
 
 # Set custom APM Server URL (default: http://localhost:8200)
 export ELASTIC_APM_SERVER_URL=
@@ -69,13 +77,16 @@ Do not add the agent as a dependency to your application.
 Add the `-javaagent` flag and configure the agent with system properties.
 
 * Set required service name
+* Set optional service version and environment
 * Set custom APM Server URL (default: http://localhost:8200)
 * Set the base package of your application
 
 [source,java]
 ----
 java -javaagent:/path/to/elastic-apm-agent-<version>.jar \
      -Delastic.apm.service_name=my-application \
+     -Delastic.apm.service_version=1.0 \
+     -Delastic.apm.environment=production \
      -Delastic.apm.server_urls=http://localhost:8200 \
      -Delastic.apm.secret_token= \
      -Delastic.apm.application_packages=org.example \
@@ -134,9 +145,11 @@ from the `appsettings.json` file:
 ----
 {
     "ElasticApm": {
-    "SecretToken": "",
-    "ServerUrls": "http://localhost:8200", //Set custom APM Server URL (default: http://localhost:8200)
-    "ServiceName" : "MyApp", //allowed characters: a-z, A-Z, 0-9, -, _, and space. Default is the entry assembly of the application
+      "SecretToken": "",
+      "ServerUrls": "http://localhost:8200", //Set custom APM Server URL (default: http://localhost:8200)
+      "ServiceName" : "MyApp", //allowed characters: a-z, A-Z, 0-9, -, _, and space. Default is the entry assembly of the application
+      "ServiceVersion" : "1.0",
+      "Environment": "production",
   }
 }
 ----
@@ -182,7 +195,11 @@ var apm = require('elastic-apm-node').start({
   // The service name for your application. This defaults to the
   // "name" field from package.json if not specified.
   // Allowed characters: a-z, A-Z, 0-9, -, _, and space
-  serviceName: ''
+  serviceName: 'my-application',
+
+  serviceVersion: '1.0',
+
+  environment: 'production'
 })
 ----
 
@@ -226,6 +243,10 @@ ELASTIC_APM = {
   # a-z, A-Z, 0-9, -, _, and space
   'SERVICE_NAME': '',
 
+  'SERVICE_VERSION': '1.0',
+
+  'ENVIRONMENT': 'production',
+
   # Use if APM Server requires a token
   'SECRET_TOKEN': '',
 
@@ -270,6 +291,10 @@ app.config['ELASTIC_APM'] = {
   # a-z, A-Z, 0-9, -, _, and space
   'SERVICE_NAME': '',
 
+  'SERVICE_VERSION': '1.0',
+
+  'ENVIRONMENT': 'production',
+
   # Use if APM Server requires a token
   'SECRET_TOKEN': '',
 
@@ -312,6 +337,10 @@ Configure the agent by creating the config file `config/elastic_apm.yml`:
 # Defaults to the name of your Rails app
 service_name: 'my-service'
 
+service_version: '1.0'
+
+environment: 'production'
+
 # Use if APM Server requires a token
 secret_token: ''
 
@@ -356,6 +385,10 @@ Create a config file config/elastic_apm.yml:
 # Defaults to the name of your Rack app's class.
 service_name: 'my-service'
 
+service_version: '1.0'
+
+environment: 'production'
+
 # Use if APM Server requires a token
 secret_token: ''