- Kibana Guide: other versions:
- What is Kibana?
- What’s new in 8.3
- Kibana concepts
- Quick start
- Set up
- Install Kibana
- Configure Kibana
- Alerting and action settings
- APM settings
- Banners settings
- Enterprise Search settings
- Fleet settings
- i18n settings
- Logging settings
- Logs settings
- Metrics settings
- Monitoring settings
- Reporting settings
- Search sessions settings
- Secure settings
- Security settings
- Spaces settings
- Task Manager settings
- Telemetry settings
- URL drilldown settings
- Start and stop Kibana
- Access Kibana
- Securing access to Kibana
- Add data
- Upgrade Kibana
- Configure security
- Configure reporting
- Configure logging
- Configure monitoring
- Command line tools
- Production considerations
- Discover
- Dashboard and visualizations
- Canvas
- Maps
- Build a map to compare metrics by country or region
- Track, visualize, and alert on assets in real time
- Map custom regions with reverse geocoding
- Heat map layer
- Tile layer
- Vector layer
- Plot big data
- Search geographic data
- Configure map settings
- Connect to Elastic Maps Service
- Import geospatial data
- Troubleshoot
- Reporting and sharing
- Machine learning
- Graph
- Alerting
- Observability
- APM
- Security
- Dev Tools
- Fleet
- Osquery
- Stack Monitoring
- Stack Management
- REST API
- Get features API
- Kibana spaces APIs
- Kibana role management APIs
- User session management APIs
- Saved objects APIs
- Data views API
- Index patterns APIs
- Alerting APIs
- Action and connector APIs
- Cases APIs
- Import and export dashboard APIs
- Logstash configuration management APIs
- Machine learning APIs
- Short URLs APIs
- Get Task Manager health
- Upgrade assistant APIs
- Kibana plugins
- Troubleshooting
- Accessibility
- Release notes
- Developer guide
Annotation API
editAnnotation API
editThe Annotation API allows you to annotate visualizations in the APM app with significant events, like deployments, allowing you to easily see how these events are impacting the performance of your existing applications.
By default, annotations are stored in a newly created observability-annotations
index.
The name of this index can be changed in your config.yml
by editing xpack.observability.annotations.index
.
If you change the default index name, you’ll also need to update your user privileges accordingly.
The following APIs are available:
- Create or update annotation to create an annotation for APM.
How to use APM APIs
editExpand for required headers, privileges, and usage details
Interact with APM APIs using cURL or another API tool. All APM APIs are Kibana APIs, not Elasticsearch APIs; because of this, the Kibana dev tools console cannot be used to interact with APM APIs.
For all APM APIs, you must use a request header.
Supported headers are Authorization
, kbn-xsrf
, and Content-Type
.
-
Authorization: ApiKey {credentials}
-
Kibana supports token-based authentication with the Elasticsearch API key service. The API key returned by the Elasticsearch create API key API can be used by sending a request with an
Authorization
header that has a value ofApiKey
followed by the{credentials}
, where{credentials}
is the base64 encoding ofid
andapi_key
joined by a colon.Alternatively, you can create a user and use their username and password to authenticate API access:
-u $USER:$PASSWORD
.Whether using
Authorization: ApiKey {credentials}
, or-u $USER:$PASSWORD
, users interacting with APM APIs must have sufficient privileges. -
kbn-xsrf: true
-
By default, you must use
kbn-xsrf
for all API calls, except in the following scenarios:-
The API endpoint uses the
GET
orHEAD
operations -
The path is allowed using the
server.xsrf.allowlist
setting -
XSRF protections are disabled using the
server.xsrf.disableProtection
setting
-
The API endpoint uses the
-
Content-Type: application/json
-
Applicable only when you send a payload in the API request.
Kibana API requests and responses use JSON.
Typically, if you include the
kbn-xsrf
header, you must also include theContent-Type
header.
Create or update annotation
editRequest
editPOST /api/apm/services/:serviceName/annotation
Request body
edit-
service
-
(required, object) Service identifying the configuration to create or update.
Properties of
service
-
version
- (required, string) Version of service.
-
environment
- (optional, string) Environment of service.
-
-
@timestamp
- (required, string) The date and time of the annotation. Must be in ISO 8601 format.
-
message
-
(optional, string) The message displayed in the annotation. Defaults to
service.version
. -
tags
-
(optional, array) Tags are used by the APM app to distinguish APM annotations from other annotations.
Tags may have additional functionality in future releases. Defaults to
[apm]
. While you can add additional tags, you cannot remove theapm
tag.
Example
editThe following example creates an annotation for a service named opbeans-java
.
curl -X POST \ http://localhost:5601/api/apm/services/opbeans-java/annotation \ -H 'Content-Type: application/json' \ -H 'kbn-xsrf: true' \ -H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \ -d '{ "@timestamp": "2020-05-08T10:31:30.452Z", "service": { "version": "1.2" }, "message": "Deployment 1.2" }'
Response body
edit{ "_index": "observability-annotations", "_id": "Lc9I93EBh6DbmkeV7nFX", "_version": 1, "_seq_no": 12, "_primary_term": 1, "found": true, "_source": { "message": "Deployment 1.2", "@timestamp": "2020-05-08T10:31:30.452Z", "service": { "version": "1.2", "name": "opbeans-java" }, "tags": [ "apm", "elastic.co", "customer" ], "annotation": { "type": "deployment" }, "event": { "created": "2020-05-09T02:34:43.937Z" } } }