[apm] Annotation API documentation #65963

bmorelli25 · 2020-05-11T03:00:43Z

Summary

This PR adds documentation for the APM annotation API.

Documentation was created by running Kibana in dev mode from master and connecting to dev-next. Privileges needed are described in #65963 (comment). Here's an example curl request (with fake ApiKey)

curl --location --request POST 'http://localhost:5601/api/apm/services/opbeans-java/annotation' \
--header 'kbn-xsrf: foo' \
--header 'Authorization: ApiKey WHnA0SwM2pzR2Vxhc286TjlIRUJWNxelR4Mkx5wLWRUYUZmdzZycm3VadJ==' \
--header 'Content-Type: application/json' \
--data-raw '{
	"@timestamp": "2020-05-05T10:31:30.452Z",
	"service": {
		"version": "1.1"
	}
}'

elasticmachine · 2020-05-11T03:00:45Z

Pinging @elastic/apm-ui (Team:apm)

bmorelli25

@dgieselaar Here's a rough draft. Still some work to do, but I have a few questions first>

docs/apm/api.asciidoc

docs/settings/apm-settings.asciidoc

docs/apm/api.asciidoc

bmorelli25 · 2020-05-11T03:24:16Z

docs/apm/api.asciidoc

+// Basic auth or API can be used
+// Need to talk about permissions req'd


When using the APM API, the user needs Kibana write permissions for APM (similar to the agent configuration APIs IIRC)

Can you be more specific? My first thought was create_doc on apm-* indices and create_index on apm-* indices, as described here, but that doesn't work. Presumably because these annotations are not stored in an index that matches that pattern.

Yeah, the user indexing the annotations needs those permissions for observability-annotations, or whatever index name they set for xpack.observability.annotations.index. Additionally, for the APM endpoint, they need feature privileges (read and write) for APM: https://www.elastic.co/guide/en/kibana/current/kibana-privileges.html.

Here are the minimum privileges I was able to get to work:

Feature: APM --> all
Index: observability-annotations. Privileges: create_index, create_doc, manage, and read.

Does this sound correct to you? This is different from what you described, but I get 500s without manage and read on observability-annotations.

You're right - when we index an annotation we read it from ES immediately after so we can return the annotation as it is stored in ES. manage is needed for checking if the index exists (view_index_metadata works as well).

bmorelli25 · 2020-05-12T16:48:09Z

@elasticmachine, run elasticsearch-ci/docs

dgieselaar · 2020-05-16T15:25:41Z

@bmorelli25 LMK when this needs a final review (IIRC this is not entirely finished yet?)

bmorelli25 · 2020-05-17T20:41:15Z

@elasticmachine merge upstream

bmorelli25 · 2020-05-17T20:42:15Z

@dgieselaar this is ready for a review! Permissions/roles will be added in a future PR as I'm not quite sure how I want to document that yet.

dgieselaar

LGTM, just a couple of suggestions. Thanks @bmorelli25 !

dgieselaar · 2020-05-19T13:31:13Z

docs/apm/api.asciidoc

+
+`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]`.


The apm tag will always be added by the endpoint, even if the user specifies other tags in the request. Should we clarify that?

dgieselaar · 2020-05-19T13:32:26Z

docs/apm/api.asciidoc

+
+// AGENT CONFIG API
+// GET --> Feature (APM) Read
+// CREAT/EDIT/DELETE --> Feature (APM) All


CREAT => CREATE?

CREAT

C R E A T

C. R. E. A. T.

* master: [apm] Annotation API documentation (elastic#65963) [Uptime] Improve responsiveness details page (elastic#67034) skip flaky suite (elastic#66669) Revert "Integration of a static filesystem for the node_modules (elastic#47998)" (elastic#67124) Support api_integration/kibana/stats against remote hosts (elastic#53000) chore(NA): add module name mapper for src plugins on x-pack (elastic#67103) Change the error message on TSVB in order to be more user friendly (elastic#67090) [kbn/optimizer] poll parent process to avoid zombie processes (elastic#67059) [Visualize] Lazy load default editor, fix duplicated styles (elastic#66732) Bump styled-component dependencies (elastic#66611) Bump react-markdown dependencies (elastic#66615) Fix Core docs links (elastic#66977) Timelion graph is not refreshing content after searching or filtering (elastic#67023) Remove `--xpack.endpoint.enabled=true` from README.md file (elastic#67053) Move apm tutorial from apm plugin into apm_oss plugin (elastic#66432) [Logs UI] Restore call to `UsageCollector.countLogs` (elastic#67051) Remove unused license check result from LP Security plugin (elastic#66966)

* master: (21 commits) [Alerting] Hides the `alert` SavedObjects type (elastic#66719) skip flaky suite (elastic#66869) fix visual baseline tests [kbn/optimizer] require fsevents on macos (elastic#67147) [APM] Fix obscured service map connections (elastic#67129) [apm] Annotation API documentation (elastic#65963) [Uptime] Improve responsiveness details page (elastic#67034) skip flaky suite (elastic#66669) Revert "Integration of a static filesystem for the node_modules (elastic#47998)" (elastic#67124) Support api_integration/kibana/stats against remote hosts (elastic#53000) chore(NA): add module name mapper for src plugins on x-pack (elastic#67103) Change the error message on TSVB in order to be more user friendly (elastic#67090) [kbn/optimizer] poll parent process to avoid zombie processes (elastic#67059) [Visualize] Lazy load default editor, fix duplicated styles (elastic#66732) Bump styled-component dependencies (elastic#66611) Bump react-markdown dependencies (elastic#66615) Fix Core docs links (elastic#66977) Timelion graph is not refreshing content after searching or filtering (elastic#67023) Remove `--xpack.endpoint.enabled=true` from README.md file (elastic#67053) Move apm tutorial from apm plugin into apm_oss plugin (elastic#66432) ...

bmorelli25 added Team:APM All issues that need APM UI Team support release_note:skip Skip the PR/issue when compiling release notes v7.8.0 labels May 11, 2020

bmorelli25 self-assigned this May 11, 2020

bmorelli25 commented May 11, 2020

View reviewed changes

bmorelli25 requested a review from dgieselaar May 11, 2020 03:41

docs: first draft annotation api

a741f9f

bmorelli25 mentioned this pull request May 11, 2020

[security] Review APM Server roles and their documentation elastic/apm-server#3596

Closed

docs: feedback

bff918c

bmorelli25 force-pushed the apm-annotation-api branch from 895846a to bff918c Compare May 11, 2020 22:33

bmorelli25 added 2 commits May 12, 2020 12:57

docs: fix build error

8c47e27

docs: fix for the fix

513a440

sorenlouv added the apm:test-plan-7.8.0 label May 13, 2020

sorenlouv unassigned bmorelli25 May 13, 2020

docs: add CURL example

5ea0e73

Merge branch 'master' into apm-annotation-api

c9aff99

bmorelli25 self-assigned this May 19, 2020

Merge branch 'master' into apm-annotation-api

4de53c3

dgieselaar approved these changes May 19, 2020

View reviewed changes

docs: finalize

bea242e

bmorelli25 merged commit 203605e into elastic:master May 20, 2020

bmorelli25 deleted the apm-annotation-api branch May 20, 2020 21:35

This was referenced May 20, 2020

[7.x] [apm] Annotation API documentation (#65963) #67142

Merged

[7.8] [apm] Annotation API documentation (#65963) #67143

Merged

bmorelli25 added a commit to bmorelli25/kibana that referenced this pull request May 20, 2020

[apm] Annotation API documentation (elastic#65963)

d4a27e3

bmorelli25 added a commit that referenced this pull request May 21, 2020

[apm] Annotation API documentation (#65963) (#67142)

c4010de

bmorelli25 added a commit that referenced this pull request May 21, 2020

[apm] Annotation API documentation (#65963) (#67143)

4aca737

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[apm] Annotation API documentation #65963

[apm] Annotation API documentation #65963

bmorelli25 commented May 11, 2020 •

edited

Loading

elasticmachine commented May 11, 2020

bmorelli25 left a comment

bmorelli25 May 11, 2020

dgieselaar May 11, 2020

bmorelli25 May 11, 2020

dgieselaar May 13, 2020

bmorelli25 commented May 12, 2020

dgieselaar commented May 16, 2020

bmorelli25 commented May 17, 2020

bmorelli25 commented May 17, 2020

dgieselaar left a comment

dgieselaar May 19, 2020

dgieselaar May 19, 2020

bmorelli25 May 20, 2020

		// Basic auth or API can be used
		// Need to talk about permissions req'd

[apm] Annotation API documentation #65963

[apm] Annotation API documentation #65963

Conversation

bmorelli25 commented May 11, 2020 • edited Loading

Summary

elasticmachine commented May 11, 2020

bmorelli25 left a comment

Choose a reason for hiding this comment

bmorelli25 May 11, 2020

Choose a reason for hiding this comment

dgieselaar May 11, 2020

Choose a reason for hiding this comment

bmorelli25 May 11, 2020

Choose a reason for hiding this comment

dgieselaar May 13, 2020

Choose a reason for hiding this comment

bmorelli25 commented May 12, 2020

dgieselaar commented May 16, 2020

bmorelli25 commented May 17, 2020

bmorelli25 commented May 17, 2020

dgieselaar left a comment

Choose a reason for hiding this comment

dgieselaar May 19, 2020

Choose a reason for hiding this comment

dgieselaar May 19, 2020

Choose a reason for hiding this comment

bmorelli25 May 20, 2020

Choose a reason for hiding this comment

C. R. E. A. T.

bmorelli25 commented May 11, 2020 •

edited

Loading