Metadataedit

Every 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.

Tip

Metadata is stored under context when viewing documents in Elasticsearch.

Kubernetes dataedit

APM 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 Schemaedit

The APM Server uses JSON Schema for validating requests. The specification for metadata is defined below:

{
    "$id": "doc/spec/metadata.json",
    "title": "Metadata",
    "description": "Metadata concerning the other objects in the stream.",
    "type": ["object"],
    "properties": {
        "service": {
            "$ref": "service.json"
        },
        "process": {
            "$ref": "process.json"
        },
        "system": {
            "$ref": "v2_system.json"
        },
        "user": {
            "$ref": "user.json"
        }
    },
    "required": ["service"]
}
Service Schemaedit
{
    "$id": "doc/spec/service.json",
    "title": "Service",
    "type": "object",
    "properties": {
        "agent": {
            "description": "Name and version of the Elastic APM agent",
            "type": "object",
            "properties": {
                "name": {
                    "description": "Name of the Elastic APM agent, e.g. \"Python\"",
                    "type": "string",
                    "maxLength": 1024
                },
                "version": {
                    "description": "Version of the Elastic APM agent, e.g.\"1.0.0\"",
                    "type": "string",
                    "maxLength": 1024
                }
            },
            "required": ["name", "version"]
        },
        "framework": {
            "description": "Name and version of the web framework used",
            "type": ["object", "null"],
            "properties": {
                "name": {
                    "type": ["string", "null"],
                    "maxLength": 1024
                },
                "version": {
                    "type": ["string", "null"],
                    "maxLength": 1024
                }
            }
        },
        "language": {
            "description": "Name and version of the programming language used",
            "type": ["object", "null"],
            "properties": {
                "name": {
                    "type": "string",
                    "maxLength": 1024
                },
                "version": {
                    "type": ["string", "null"],
                    "maxLength": 1024
                }
            },
            "required": ["name"]
        },
        "name": {
            "description": "Immutable name of the service emitting this event",
            "type": "string",
            "pattern": "^[a-zA-Z0-9 _-]+$",
            "maxLength": 1024
        },
        "environment": {
            "description": "Environment name of the service, e.g. \"production\" or \"staging\"",
            "type": ["string", "null"],
            "maxLength": 1024
        },
        "runtime": {
            "description": "Name and version of the language runtime running this service",
            "type": ["object", "null"],
            "properties": {
                "name": {
                    "type": "string",
                    "maxLength": 1024
                },
                "version": {
                    "type": "string",
                    "maxLength": 1024
                }
            },
            "required": ["name", "version"]
        },
        "version": {
            "description": "Version of the service emitting this event",
            "type": ["string", "null"],
            "maxLength": 1024
        }
    },
    "required": ["agent", "name"]
}
Process Schemaedit
{
  "$id": "doc/spec/process.json",
  "title": "Process",
  "type": ["object", "null"],
  "properties": {
      "pid": {
          "description": "Process ID of the service",
          "type": ["integer"]
      },
      "ppid": {
          "description": "Parent process ID of the service",
          "type": ["integer", "null"]
      },
      "title": {
          "type": ["string", "null"],
          "maxLength": 1024
      },
      "argv": {
        "description": "Command line arguments used to start this process",
        "type": ["array", "null"],
        "minItems": 0,
        "items": {
           "type": "string"
        }
    }
  },
  "required": ["pid"]
}
System Schemaedit
{
    "$id": "doc/spec/v2_system.json",
    "title": "System",
    "type": ["object", "null"],
    "allOf": [
        { "$ref": "common_system.json"  },
        {
            "properties": {
                "kubernetes": {
                    "properties": {
                        "namespace": {
                            "description": "Kubernetes namespace",
                            "type": ["string", "null"],
                            "maxLength": 1024
                        },
                        "pod":{
                            "properties": {
                                "name": {
                                    "description": "Kubernetes pod name",
                                    "type": ["string", "null"],
                                    "maxLength": 1024
                                },
                                "uid": {
                                    "description": "Kubernetes pod uid",
                                    "type": ["string", "null"],
                                    "maxLength": 1024
                                }
                            }
                        },
                        "node":{
                            "properties": {
                                "name": {
                                    "description": "Kubernetes node name",
                                    "type": ["string", "null"],
                                    "maxLength": 1024
                                }
                            }
                        }
                    }
                },
                "container": {
                    "properties": {
                        "id" : {
                            "description": "Container ID",
                            "type": ["string"],
                            "maxLength": 1024
                        }
                    },
                    "required": ["id"]
                }
            }
        }
    ]
}
User Schemaedit
{
    "$id": "docs/spec/user.json",
    "title": "User",
    "description": "Describes the authenticated User for a request.",
    "type": ["object", "null"],
    "properties": {
        "id": {
            "description": "Identifier of the logged in user, e.g. the primary key of the user",
            "type": ["string", "integer", "null"],
            "maxLength": 1024
        },
        "email": {
            "description": "Email of the logged in user",
            "type": ["string", "null"],
            "maxLength": 1024
        },
        "username": {
            "description": "The username of the logged in user",
            "type": ["string", "null"],
            "maxLength": 1024
        }
    }
}