The Elastic APM integration became generally available in 7.16 — see the APM Guide for updated documentation. Standalone APM Server users can see the Legacy APM Overview and Legacy APM Server Reference.
Metadata
editMetadata
editEvery new connection to the APM Server starts with a metadata stanza.
This provides general metadata concerning the other objects in the stream.
Rather than send this metadata information from the agent multiple times, the APM Server hangs on to this information and applies it to other objects in the stream as necessary.
Metadata is stored under context when viewing documents in Elasticsearch.
Kubernetes data
editAPM agents automatically read kubernetes data and send it to the APM Server. In most instances, agents are able to read this data from inside the container. If this is not the case, or if you wish to override this data, you can set environment variables for the agents to read. These environment variable are set via the kubernetes Downward API. Here’s how you would add the environment variables to your kubernetes pod spec:
- name: KUBERNETES_NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: KUBERNETES_POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: KUBERNETES_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: KUBERNETES_POD_UID
valueFrom:
fieldRef:
fieldPath: metadata.uid
The table below maps these environment variables to the APM metadata event field:
| Environment variable | Metadata field name |
|---|---|
KUBERNETES_NODE_NAME |
system.kubernetes.node.name |
KUBERNETES_POD_NAME |
system.kubernetes.pod.name |
KUBERNETES_NAMESPACE |
system.kubernetes.namespace |
KUBERNETES_POD_UID |
system.kubernetes.pod.uid |
Metadata Schema
editAPM Server uses JSON Schema to validate requests. The specification for metadata is defined on GitHub and included below:
{
"$id": "docs/spec/v2/metadata",
"type": "object",
"properties": {
"cloud": {
"description": "Cloud metadata about where the monitored service is running.",
"type": [
"null",
"object"
],
"properties": {
"account": {
"description": "Account where the monitored service is running.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID of the cloud account.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"name": {
"description": "Name of the cloud account.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"availability_zone": {
"description": "AvailabilityZone where the monitored service is running, e.g. us-east-1a",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"instance": {
"description": "Instance on which the monitored service is running.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID of the cloud instance.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"name": {
"description": "Name of the cloud instance.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"machine": {
"description": "Machine on which the monitored service is running.",
"type": [
"null",
"object"
],
"properties": {
"type": {
"description": "ID of the cloud machine.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"project": {
"description": "Project in which the monitored service is running.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID of the cloud project.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"name": {
"description": "Name of the cloud project.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"provider": {
"description": "Provider that is used, e.g. aws, azure, gcp, digitalocean.",
"type": "string",
"maxLength": 1024
},
"region": {
"description": "Region where the monitored service is running, e.g. us-east-1",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"service": {
"description": "Service that is monitored on cloud",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the cloud service, intended to distinguish services running on different platforms within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
},
"required": [
"provider"
]
},
"labels": {
"description": "Labels are a flat mapping of user-defined tags. Allowed value types are string, boolean and number values. Labels are indexed and searchable.",
"type": [
"null",
"object"
],
"additionalProperties": {
"type": [
"null",
"string",
"boolean",
"number"
],
"maxLength": 1024
}
},
"network": {
"description": "Network holds information about the network over which the monitored service is communicating.",
"type": [
"null",
"object"
],
"properties": {
"connection": {
"type": [
"null",
"object"
],
"properties": {
"type": {
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
}
},
"process": {
"description": "Process metadata about the monitored service.",
"type": [
"null",
"object"
],
"properties": {
"argv": {
"description": "Argv holds the command line arguments used to start this process.",
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"minItems": 0
},
"pid": {
"description": "PID holds the process ID of the service.",
"type": "integer"
},
"ppid": {
"description": "Ppid holds the parent process ID of the service.",
"type": [
"null",
"integer"
]
},
"title": {
"description": "Title is the process title. It can be the same as process name.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
},
"required": [
"pid"
]
},
"service": {
"description": "Service metadata about the monitored service.",
"type": "object",
"properties": {
"agent": {
"description": "Agent holds information about the APM agent capturing the event.",
"type": "object",
"properties": {
"ephemeral_id": {
"description": "EphemeralID is a free format ID used for metrics correlation by agents",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"name": {
"description": "Name of the APM agent capturing information.",
"type": "string",
"maxLength": 1024,
"minLength": 1
},
"version": {
"description": "Version of the APM agent capturing information.",
"type": "string",
"maxLength": 1024
}
},
"required": [
"name",
"version"
]
},
"environment": {
"description": "Environment in which the monitored service is running, e.g. `production` or `staging`.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"framework": {
"description": "Framework holds information about the framework used in the monitored service.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the used framework",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"version": {
"description": "Version of the used framework",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"language": {
"description": "Language holds information about the programming language of the monitored service.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the used programming language",
"type": "string",
"maxLength": 1024
},
"version": {
"description": "Version of the used programming language",
"type": [
"null",
"string"
],
"maxLength": 1024
}
},
"required": [
"name"
]
},
"name": {
"description": "Name of the monitored service.",
"type": "string",
"maxLength": 1024,
"minLength": 1,
"pattern": "^[a-zA-Z0-9 _-]+$"
},
"node": {
"description": "Node must be a unique meaningful name of the service node.",
"type": [
"null",
"object"
],
"properties": {
"configured_name": {
"description": "Name of the service node",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"runtime": {
"description": "Runtime holds information about the language runtime running the monitored service",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the language runtime",
"type": "string",
"maxLength": 1024
},
"version": {
"description": "Name of the language runtime",
"type": "string",
"maxLength": 1024
}
},
"required": [
"name",
"version"
]
},
"version": {
"description": "Version of the monitored service.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
},
"required": [
"agent",
"name"
]
},
"system": {
"description": "System metadata",
"type": [
"null",
"object"
],
"properties": {
"architecture": {
"description": "Architecture of the system the monitored service is running on.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"configured_hostname": {
"description": "ConfiguredHostname is the configured name of the host the monitored service is running on. It should only be sent when configured by the user. If given, it is used as the event's hostname.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"container": {
"description": "Container holds the system's container ID if available.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID of the container the monitored service is running in.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"detected_hostname": {
"description": "DetectedHostname is the hostname detected by the APM agent. It usually contains what the hostname command returns on the host machine. It will be used as the event's hostname if ConfiguredHostname is not present.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"hostname": {
"description": "Deprecated: Use ConfiguredHostname and DetectedHostname instead. DeprecatedHostname is the host name of the system the service is running on. It does not distinguish between configured and detected hostname and therefore is deprecated and only used if no other hostname information is available.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"kubernetes": {
"description": "Kubernetes system information if the monitored service runs on Kubernetes.",
"type": [
"null",
"object"
],
"properties": {
"namespace": {
"description": "Namespace of the Kubernetes resource the monitored service is run on.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"node": {
"description": "Node related information",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the Kubernetes Node",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"pod": {
"description": "Pod related information",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the Kubernetes Pod",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"uid": {
"description": "UID is the system-generated string uniquely identifying the Pod.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
}
},
"platform": {
"description": "Platform name of the system platform the monitored service is running on.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"user": {
"description": "User metadata, which can be overwritten on a per event basis.",
"type": [
"null",
"object"
],
"properties": {
"domain": {
"description": "Domain of the logged in user",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"email": {
"description": "Email of the user.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"id": {
"description": "ID identifies the logged in user, e.g. can be the primary key of the user",
"type": [
"null",
"string",
"integer"
],
"maxLength": 1024
},
"username": {
"description": "Name of the user.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
},
"required": [
"service"
]
}