Docs improvements #548

roncohen · 2018-01-25T15:14:28Z

added:

configuration through a file
command reference
logging configuration
path config
directory layout
dashboard set and dashboard config
elasticsearch output config
enabling SSL for the Elasticsearch output
env var configuration
configuring the Kibana endpoint
configuring auto template loading
manual template loading

Moved some sections around:

Main headline is "APM Server Reference (Beta)" now
Reordered the intake API under a section

relies on elastic/beats#6184
related: #440

roncohen · 2018-01-25T20:33:14Z

There's a bunch of this we need to test before we merge

roncohen · 2018-01-25T21:48:05Z

docs/copied-from-beats/command-reference.asciidoc

+Use `sudo` to run the following commands if:
+
+* the config file is owned by `root`, or
+* {beatname_uc} is configured to capture data that requires `root` access


this is a bit weird for APM Server, but i guess this could be taken to mean if you set it up to listen on port < 1025, you'll need to run it as root.

roncohen · 2018-01-25T22:00:28Z

When this gets merged, we should update our copy: elastic/beats#6186

simitt · 2018-01-26T08:12:31Z

docs/intake-api.asciidoc

+
+include::./transaction-api.asciidoc[]
+
+include::./error-api.asciidoc[]


looks like we agree on that ;) https://github.com/elastic/apm-server/pull/549/files#diff-528ff8e4a5598922b19d2e267575d5a8

simitt · 2018-01-26T12:02:50Z

@roncohen could you add a note regarding this Issue #519 in the dashboards doc section?

roncohen · 2018-01-26T14:54:49Z

docs/copied-from-beats/dashboards.asciidoc

+
+["source","sh",subs="attributes,callouts"]
+----------------------------------------------------------------------
+PS > {beatname_lc} setup --dashboards


I have not had a chance to test this.

elastic/beats#6196

roncohen · 2018-01-26T17:04:09Z

@simitt is this what you had in mind?: elastic/beats#6197

simitt

I am not through yet, but here are some first review comments.

simitt · 2018-01-29T10:02:20Z

docs/installing.asciidoc

I liked having the Docker guide also referenced in the installation section, as it is an alternative to installing APM Server nativly.

The distinction into downloading or installing from repos/on windows, seems a bit constructed, as for windows you also need to download first.
How about having 4 sections that are subpages describing the options for the specific OS:

Installation on Windows

Installation on Linux

Installation on Mac OS

Installation with Docker

that's a good idea. I'll merge this now so we at least have something and then we can iterate on it

simitt · 2018-01-29T10:05:14Z

docs/copied-from-beats/shared-configuring.asciidoc

+you'll find the configuration file at +/etc/{beatname_lc}/{beatname_lc}.yml+. Under
+Docker, it's located at +/usr/share/{beatname_lc}/{beatname_lc}.yml+. For mac and win,
+look in the archive that you just extracted. There’s also a full example
+configuration file called +{beatname_lc}.reference.yml+ that shows all non-deprecated


how about actively supported instead of non-deprecated?

I like that non-deprecated make it explicit that we're not including deprecated stuff. "actively supported" could mean that we support it in the discuss forum or on subscriptions.

simitt · 2018-01-29T10:09:20Z

docs/copied-from-beats/shared-configuring.asciidoc

+
+See the
+{libbeat}/config-file-format.html[Config File Format] section of the
+_Beats Platform Reference_ for more about the structure of the config file.


This is not rendered as a link for me:

same, i think it should be fixed in the live version though

simitt · 2018-01-29T10:22:46Z

docs/copied-from-beats/loggingconfig.asciidoc

+==== `logging.level`
+
+Minimum log level. One of `debug`, `info`, `warning`, or `error`. The default
+log level is `info`.


I tested this and found the following:

log level warning actually needs to be warn, otherwise an error is thrown and the server doesn't start.

log level error still outputs info and warn logs.

log level warn still outputs info logs.

We'll need to address this in beats.

@roncohen after this being fixed in beats I think you need to change warn back to warning.

@simitt already done! :)

simitt · 2018-01-29T10:28:24Z

docs/copied-from-beats/loggingconfig.asciidoc

+When true, writes all logging output to the Windows Event Log.
+
+[float]
+==== `logging.to_files`


Did you test this? I tried to use log files, by copying over the example, but the files have not been created.

resolved on chat, works

simitt · 2018-01-29T10:52:38Z

docs/copied-from-beats/outputconfig.asciidoc

+need to configure the `setup.template.name` and `setup.template.pattern` options
+(see <<configuration-template>>). If you are using the pre-built Kibana
+dashboards, you also need to set the `setup.dashboards.index` option (see
+<<configuration-dashboards>>).


You could also mention that the index for Sourcemaps needs to be changed here. (Except if we don't want to cross reference to experimental features).

let's wait for now

simitt · 2018-01-29T10:55:09Z

docs/copied-from-beats/outputconfig.asciidoc

+
+*`mapping`*: Dictionary mapping index names to new names
+
+*`default`*: Default string value if `mapping` does not find a match.


I find the mapping and default option rather confusing, as they don't show up in the example, and I think the specified index pattern is simply used as default if nothing else found.
If the two options can be specifically set then they should go into the example.

will make a note to suggest to beats

simitt · 2018-01-29T10:56:30Z

docs/copied-from-beats/outputconfig.asciidoc

+
+The number of times to retry publishing an event after a publishing failure.
+After the specified number of retries, the events are typically dropped.
+Some Beats, such as Filebeat, ignore the `max_retries` setting and retry until all


Can you remove this line as APM Server has nothing to do with Filebeat

simitt · 2018-01-29T11:03:08Z

docs/copied-from-beats/shared-template-load.asciidoc

+==== Load the template manually
+
+To load the template manually, run the <<setup-command,`setup`>> command. A
+connection to Elasticsearch is required. If Logstash output is enabled, you need


We don't support logstash output.

simitt · 2018-01-29T11:06:04Z

docs/copied-from-beats/command-reference.asciidoc

+//// Use the following include to pull this content into a doc file:
+//// include::../../libbeat/docs/command-reference.asciidoc[]
+//////////////////////////////////////////////////////////////////////////
+


I don't think that we should mention machine learning here.

fixed here: elastic/beats@91b8c7b

simitt

Thanks for adding all this documentation @roncohen. Had a couple of comments, but overall looks quite good.

simitt · 2018-01-29T13:25:56Z

docs/copied-from-beats/dashboards.asciidoc

+This requires a Kibana endpoint configuration. You should have configured the
+endpoint earlier when you
+<<{beatname_lc}-configuration,configured {beatname_uc}>>. If you didn't,
+configure it now.


Actually the config part comes after. this, so saying you should have configured the endpoint earlier is a bit confusing.
I suggest to completely remove this NOTE section. Instead only link to the configure dashboard loading, which itself should link to the Kibana API setup section.

simitt · 2018-01-29T13:29:20Z

docs/copied-from-beats/dashboards.asciidoc

+
+Make sure Kibana is running before you perform this step. If you are accessing a
+secured Kibana instance, make sure you've configured credentials as described in
+<<{beatname_lc}-configuration>>.


this renders to Configuring APM Server with a capital C in the middle of the sentence.

simitt · 2018-01-29T13:36:18Z

docs/copied-from-beats/dashboards.asciidoc

+<<{beatname_lc}-configuration>>.
+
+To set up the Kibana dashboards for {beatname_uc}, use the appropriate command
+for your system.


The next section is an overview over APM Server cmds, as the instruction for the Power Shell is valid for all instructions, how about adding the Powershell instruction here instead:

good idea, will do it in beats in a separate PR when this is done.

simitt · 2018-01-29T13:43:08Z

docs/copied-from-beats/dashboards.asciidoc

+
+From the PowerShell prompt, change to the directory where you installed {beatname_uc},
+and run:
+


Something is very strange regarding including setup cmd here, I see Power shell instructions on a non-windows machine:

i think thats fixed then it goes live

simitt · 2018-01-29T13:49:46Z

docs/copied-from-beats/shared-template-load.asciidoc

+
+ifndef::only-elasticsearch[]
+NOTE: A connection to Elasticsearch is required to load the index template. If
+the output is Logstash, you must


I would remove all descriptions for Logstash output as we don't describe it anywhere as possible output option.

see the ifndef::only-elasticsearch[] line above. only-elasticsearch is defined for APM Server so these lines should not show up.

added: * command reference * logging configuration * path config * directory layout

…tion.

…at for filebeat

following elastic/beats#6240

simitt

Apart from the one comment I left LGTM.

Could you please ensure to create Issues for comments where you mentioned to fix within the next iterations.

Major restructure. Adds many documents from beats that are applicable to APM Server.

roncohen added in progress docs v6.2 labels Jan 25, 2018

roncohen commented Jan 25, 2018

View reviewed changes

simitt reviewed Jan 26, 2018

View reviewed changes

This was referenced Jan 26, 2018

Document how to use environment variables to configure APM server #440

Closed

Update Documentation for APM-Server #274

Closed

roncohen commented Jan 26, 2018

View reviewed changes

roncohen changed the title ~~WIP on docs improvements~~ Docs improvements Jan 26, 2018

roncohen added review and removed in progress labels Jan 26, 2018

simitt reviewed Jan 29, 2018

View reviewed changes

roncohen force-pushed the docs-update branch from 2b47388 to 7729692 Compare January 31, 2018 12:27

Ron Cohen added 12 commits February 1, 2018 09:54

WIP on docs improvements

24713c0

added: * command reference * logging configuration * path config * directory layout

Moved some sections around and updated with more generic beats docs

c59568b

Add missing files dashboards and template-config.

45fa77b

-inging headlines like before.

f5eb1cd

Update TOC for Configuring APM Server

d00e155

Updated following elastic/beats@a58c36a

518a9d9

Added "setting up and running" to the overview TOC.

3ef09a6

Updated following elastic/beats@cf4c3b9

9a8a6d1

Updated command reference following elastic/beats@2584eba

d228c8d

Update SSL settings headline

7f5cedd

Updated template config following a beats update

764b69c

Logging config update.

63f5379

Ron Cohen added 13 commits February 1, 2018 09:54

Use specific beat name in shared-kibana-config.asciidoc

1aab0ef

Add html_docs to .gitignore

bebc104

Add .\ for PS instruction and make it possible to remove logstash men…

294aeee

…tion.

Switch kibana endpoint and kibana conf around

bbfa6da

Introduce 'has_ml_jobs'.

a0a482a

Less blamy text, removed 6.0 note, links to the correct place now

86bb134

better output config text for elasticsearch

a405c89

Better wording in configuration.

7bb506d

Only talk about Filebeat for filebeat docs

08401f8

Fix list in output config

295b4f2

It's 'warn', not 'warning'. Found by @simitt

d55da13

Update the rest of the max_retries sections to only talk about Filebe…

3766314

…at for filebeat

Special case for apm-server as it was only introduced in 6.0

0b79cce

roncohen force-pushed the docs-update branch from 1787c6a to 0b79cce Compare February 1, 2018 08:55

Ron Cohen added 6 commits February 1, 2018 10:03

Missing double quotes caused build to fail.

d3eeada

Moved Frontend support under Configuring + more restructure.

0e5d9cf

Add intake-api back in.

2fedfbf

Removing "beta release" header.

1bd0e7d

Revert changes related to warn vs warning

222618d

following elastic/beats#6240

Remove page header files

0facb0f

simitt approved these changes Feb 1, 2018

View reviewed changes

roncohen merged commit 7b69482 into elastic:master Feb 1, 2018

roncohen added a commit to roncohen/apm-server that referenced this pull request Feb 1, 2018

Docs improvements (elastic#548)

c58150f

Major restructure. Adds many documents from beats that are applicable to APM Server.

roncohen mentioned this pull request Feb 1, 2018

[6.2] Docs improvements (#548) #604

Merged

roncohen added a commit that referenced this pull request Feb 1, 2018

Docs improvements (#548) (#604)

dd9ee38

Major restructure. Adds many documents from beats that are applicable to APM Server.

roncohen added a commit to roncohen/apm-server that referenced this pull request Feb 1, 2018

Docs improvements (elastic#548)

21feaa5

Major restructure. Adds many documents from beats that are applicable to APM Server.

roncohen mentioned this pull request Feb 1, 2018

[6.x] Docs improvements (#548) #606

Merged

roncohen added a commit that referenced this pull request Feb 1, 2018

Docs improvements (#548) (#606)

9c5bc61

Major restructure. Adds many documents from beats that are applicable to APM Server.

roncohen mentioned this pull request Feb 5, 2018

Document logging options #542

Closed


		include::./transaction-api.asciidoc[]

		include::./error-api.asciidoc[]


		`mapping`: Dictionary mapping index names to new names

		`default`: Default string value if `mapping` does not find a match.


		From the PowerShell prompt, change to the directory where you installed {beatname_uc},
		and run:

Docs improvements #548

Docs improvements #548

Conversation

roncohen commented Jan 25, 2018 • edited by alvarolobato Loading

roncohen commented Jan 25, 2018

Choose a reason for hiding this comment

roncohen commented Jan 25, 2018

Choose a reason for hiding this comment

simitt commented Jan 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roncohen commented Jan 26, 2018

simitt 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

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

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

simitt 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

Choose a reason for hiding this comment

simitt left a comment

Choose a reason for hiding this comment

roncohen commented Jan 25, 2018 •

edited by alvarolobato

Loading