Update docs for metadata_processors #13650

ChrsMark · 2019-09-12T13:13:21Z

This is a follow-up for the PRs that enabled auto-detection for add_docker_metadata and add_kubernetes_metadata.

Part of: #13068
Related to:

Signed-off-by: chrismark <chrismarkou92@gmail.com>

jsoriano · 2019-09-12T15:35:43Z

libbeat/docs/processors-using.asciidoc

+-------------------------------------------------------------------------------
+processors:
+- add_kubernetes_metadata: ~
+-------------------------------------------------------------------------------


I think there is no need to add sample configuration, there is already some configuration examples some lines below.

jsoriano · 2019-09-12T15:45:09Z

libbeat/docs/processors-using.asciidoc

+-------------------------------------------------------------------------------
+processors:
+- add_docker_metadata: ~
+-------------------------------------------------------------------------------


Same here, I think there is no need to add another configuration example.

jsoriano · 2019-09-12T15:47:08Z

libbeat/docs/processors-using.asciidoc

-metadata based on which Kubernetes pod the event originated from. Each event is
-annotated with:
+metadata based on which Kubernetes pod the event originated from.
+At startup it will detect an `in_cluster` environment and cache the Kubernetes related metadata.


I think that we should more explicitly say that it will get Kubernetes-related metadata only if it finds a working configuration. Same thing for docker.

Signed-off-by: chrismark <chrismarkou92@gmail.com>

jsoriano

👍

ChrsMark · 2019-09-13T14:18:09Z

Shall we wait for Marjorie to have a look? @Titch990

Titch990

Looks fine, apart from these tiny things, but they seem to affect almost every line! I think I've picked up everything consistently across all the lines, but do check.

You could also consider using consistent phrasing in the Kubernetes and Docker sections where the functionality is equivalent (I know there are some differences too). If you do that, either set of words is OK.

Titch990 · 2019-09-13T18:42:53Z

libbeat/docs/processors-using.asciidoc

-metadata based on which Kubernetes pod the event originated from. Each event is
-annotated with:
+metadata based on which Kubernetes pod the event originated from.
+At startup it will detect an `in_cluster` environment and cache the


Suggested change

At startup it will detect an `in_cluster` environment and cache the

At startup it detects an `in_cluster` environment and caches the

Present tense is usually preferred, otherwise it reads like something you haven't yet implemented and you're describing what it will do when you have!

However, perhaps it may be more accurate to say "If it detects an in_cluster environment, it caches the Kubernetes-related metadata"? I'm not sure of your exact meaning.

Titch990 · 2019-09-13T18:49:42Z

libbeat/docs/processors-using.asciidoc

+metadata based on which Kubernetes pod the event originated from.
+At startup it will detect an `in_cluster` environment and cache the
+Kubernetes related metadata. If it's not able to detect a valid Kuberentes
+configuration, the events will not be annotated with Kubernetes related


Suggested change

configuration, the events will not be annotated with Kubernetes related

configuration, the events are not annotated with Kubernetes-related

And again . . .

Titch990 · 2019-09-13T18:50:13Z

libbeat/docs/processors-using.asciidoc

+At startup it will detect an `in_cluster` environment and cache the
+Kubernetes related metadata. If it's not able to detect a valid Kuberentes
+configuration, the events will not be annotated with Kubernetes related
+metadata. Events will be annotated only if a valid configuration was detected.


Suggested change

metadata. Events will be annotated only if a valid configuration was detected.

metadata. Events are annotated only if a valid configuration is detected.

I'd also put the positive statement first "Events are only annotated if a valid configuration is detected",, then what happens if not.

Titch990 · 2019-09-13T18:57:32Z

libbeat/docs/processors-using.asciidoc

@@ -1360,7 +1365,11 @@ case you want to specify your own.
 === Add Docker metadata

 The `add_docker_metadata` processor annotates each event with relevant metadata
-from Docker containers:
+from Docker containers. At startup it will detect a docker environment and cache the metadata.


Suggested change

from Docker containers. At startup it will detect a docker environment and cache the metadata.

from Docker containers. At startup it detects a Docker environment and caches the metadata.

Titch990 · 2019-09-13T19:03:31Z

libbeat/docs/processors-using.asciidoc

-from Docker containers:
+from Docker containers. At startup it will detect a docker environment and cache the metadata.
+The events will be annotated with Docker metadata, only if a valid configuration
+was detected and the processor is able to reach Docker api.


Suggested change

was detected and the processor is able to reach Docker api.

is detected and the processor is able to reach Docker API.

Not

Titch990 · 2019-09-13T19:03:44Z

libbeat/docs/processors-using.asciidoc

@@ -1360,7 +1365,11 @@ case you want to specify your own.
 === Add Docker metadata

 The `add_docker_metadata` processor annotates each event with relevant metadata
-from Docker containers:
+from Docker containers. At startup it will detect a docker environment and cache the metadata.
+The events will be annotated with Docker metadata, only if a valid configuration


Suggested change

The events will be annotated with Docker metadata, only if a valid configuration

The events are annotated with Docker metadata, only if a valid configuration

Titch990 · 2019-09-13T19:05:00Z

libbeat/docs/processors-using.asciidoc

-annotated with:
+metadata based on which Kubernetes pod the event originated from.
+At startup it will detect an `in_cluster` environment and cache the
+Kubernetes related metadata. If it's not able to detect a valid Kuberentes


Suggested change

Kubernetes related metadata. If it's not able to detect a valid Kuberentes

Kubernetes-related metadata. If it's not able to detect a valid Kubernetes

Signed-off-by: chrismark <chrismarkou92@gmail.com>

ChrsMark · 2019-09-16T07:04:02Z

Thank you for your suggestions Marjorie! I think all of them were addressed. Could you give a final confirmation? @Titch990

Titch990 · 2019-09-18T16:26:37Z

LGTM!

Update docs

048365c

Signed-off-by: chrismark <chrismarkou92@gmail.com>

ChrsMark added containers Related to containers use case [zube]: In Review Team:Integrations Label for the Integrations team labels Sep 12, 2019

ChrsMark self-assigned this Sep 12, 2019

ChrsMark mentioned this pull request Sep 12, 2019

Automatically enable add_docker_metadata or add_kubernetes_metadata #13068

Closed

ChrsMark added the docs label Sep 12, 2019

jsoriano reviewed Sep 12, 2019

View reviewed changes

jsoriano requested a review from Titch990 September 12, 2019 15:48

Improve docs

f1bbf33

Signed-off-by: chrismark <chrismarkou92@gmail.com>

ChrsMark requested a review from jsoriano September 13, 2019 06:46

jsoriano approved these changes Sep 13, 2019

View reviewed changes

Titch990 approved these changes Sep 13, 2019

View reviewed changes

Improve phrasing

505bb83

Signed-off-by: chrismark <chrismarkou92@gmail.com>

ChrsMark requested a review from Titch990 September 18, 2019 12:53

ChrsMark merged commit e598d6c into elastic:master Sep 19, 2019

zube bot added [zube]: Done and removed [zube]: In Review labels Sep 19, 2019

ChrsMark added the v7.5.0 label Sep 24, 2019

andresrc removed the [zube]: Done label Sep 24, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for metadata_processors #13650

Update docs for metadata_processors #13650

ChrsMark commented Sep 12, 2019 •

edited by zube bot

Loading

jsoriano Sep 12, 2019

jsoriano Sep 12, 2019

jsoriano Sep 12, 2019

jsoriano left a comment

ChrsMark commented Sep 13, 2019

Titch990 left a comment

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

Titch990 Sep 13, 2019

ChrsMark commented Sep 16, 2019

Titch990 commented Sep 18, 2019

	At startup it will detect an `in_cluster` environment and cache the
	At startup it detects an `in_cluster` environment and caches the

	configuration, the events will not be annotated with Kubernetes related
	configuration, the events are not annotated with Kubernetes-related

	metadata. Events will be annotated only if a valid configuration was detected.
	metadata. Events are annotated only if a valid configuration is detected.

	from Docker containers. At startup it will detect a docker environment and cache the metadata.
	from Docker containers. At startup it detects a Docker environment and caches the metadata.

	was detected and the processor is able to reach Docker api.
	is detected and the processor is able to reach Docker API.

	The events will be annotated with Docker metadata, only if a valid configuration
	The events are annotated with Docker metadata, only if a valid configuration

	Kubernetes related metadata. If it's not able to detect a valid Kuberentes
	Kubernetes-related metadata. If it's not able to detect a valid Kubernetes

Update docs for metadata_processors #13650

Update docs for metadata_processors #13650

Conversation

ChrsMark commented Sep 12, 2019 • edited by zube bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsoriano left a comment

Choose a reason for hiding this comment

ChrsMark commented Sep 13, 2019

Titch990 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChrsMark commented Sep 16, 2019

Titch990 commented Sep 18, 2019

ChrsMark commented Sep 12, 2019 •

edited by zube bot

Loading