[docs] APM Server install and run structure#2170
Conversation
simitt
left a comment
simitt
left a comment
There was a problem hiding this comment.
Haven't had time to go into detail yet, but I really like the proposed overall structure.
bmorelli25
force-pushed
the
revamp-apm-server-docs
branch
from
47bad0d to
15fd624
Compare
bmorelli25
changed the title
|
@jalvz / @simitt -- I'd like some feedback from you on important steps when installing APM Server. Right now I have this: Step 1: Install APM Server Does it make sense to also include a step for "Load the index template in Elasticsearch"? Beats does this, and it looks something like this: Step 1: Install APM Server Thoughts? Beats also includes a step for loading dashboards, which doesn't make sense in our case, but are there other steps that you think are important that would be good to include here? Still WIP, but here's a live view of what this looks like right now: http://apm-server_2170.docs-preview.app.elstc.co/guide/en/apm/server/master/getting-started-apm-server.html |
|
I don't have any strong opinion on step 3 (server should do that already on startup), but maybe is a good idea to make it explicit so that people are aware of it (as a downside: it is one step more which might feel awkward to people using eg. systemd) Maybe is sensible (instead of step 3?) to add an step after "start server" of verifying that everything looks fine in logs (elasticsearch connected, pipeline registered, template loaded, rum enabled - if it was configured), etc. It looks good to me either way |
|
Thanks @jalvz, that's helpful feedback! |
bmorelli25
force-pushed
the
revamp-apm-server-docs
branch
from
81ac5be to
8794206
Compare
|
This PR is finally ready for review. Since this is a bigger PR, it'd be great to feedback from both of you! A preview of the changes is available here: http://apm-server_2170.docs-preview.app.elstc.co/diff |
| In Elasticsearch, {ref}/indices-templates.html[index templates] are used to define settings | ||
| and mappings that determine how fields should be analyzed. | ||
|
|
||
| The recommended index template file for {beatname_uc} is installed by the {beatname_uc} packages. |
There was a problem hiding this comment.
I'd said before I don't have a strong opinion about this part, but given how many issues users are facing because of this, I changed my mind.
I think this is good. 99% of times I prefer concision, but here I'd add some points about:
- The APM UI relies on specific mappings, and changing them might break it.
- Users can run
apm-server -e setup templateto force a template overwrite; andapm-server export templateto see what is the template bundled with apm-server and compare it with the actual template in their elasticsearch instance. - Note that index templates are not applied retrospectively, but only to indices created from then on. For APM, this usually means one day, or whatever indicates the ILM policy (if there is one).
- Consider a troubleshooting section in Kibana mentioning that certain errors happen because of having the wrong template installed, linking back to this section and ILM manual setup. Feel free to sync up with the apm-ui team for this.
There was a problem hiding this comment.
Added in your recommendations, thanks!
Consider a troubleshooting section in Kibana mentioning that certain errors happen because of having the wrong template installed, linking back to this section and ILM manual setup. Feel free to sync up with the apm-ui team for this.
I'm going to leave the last bullet point for when I tackle #2470
|
|
||
| [[setting-up-and-running]] | ||
| == Setting up and running APM Server | ||
| == Setting up APM Server |
There was a problem hiding this comment.
I'd consider renaming this section, as generally (and vaguely) "set up" implies install + configure, which is already covered. The best I could come up with is "Operating APM Server", which I don't think is too bad; but maybe you have better ideas (or are happy with "Setting up"!)
There was a problem hiding this comment.
This section is really tough because it's kind of a mishmash of topics.
Directory layout and Secrets Keystore could really be at the beginning of the "Configuring APM Server" section. And APM Server and Systemd could be in the "Getting Started" section. I understand why High Availability was put here initially, but I don't think it really makes sense in this section.
I'm not opposed to the name "Operating APM Server", but I wonder if there's more we can do to clean this up.
There was a problem hiding this comment.
Much agreed. Feel free to move those sections, in this or other PR
|
|
||
| endif::[] | ||
|
|
||
| [[linux]] |
There was a problem hiding this comment.
I'd reconsider the order of the sections to deb, rpm, linux, mac, windows, and Running on Docker:
Maybe is a good idea also to rename linux to other linux, and change casing to Linux, Mac, Windows, and maybe RPM and DEB too.
If you change anything here, make sure it is consistent elsewhere... I am sort of sensing that you have your good reasons to use lower case there, but eg. in http://apm-server_2170.docs-preview.app.elstc.co/guide/en/apm/server/master/running-with-systemd.html is RPM and DEB :)
Speaking of which: http://apm-server_2170.docs-preview.app.elstc.co/guide/en/apm/server/master/running-with-systemd.html shouldn't be embedded in or linked to the running section?
There was a problem hiding this comment.
These are good points. I've made some updates.
From what I can tell, the correct capitalization is deb and RPM. The only reason I had everything capitalized the other way was because that's how Beats does it... in other words, not a very good reason. I'll update these on our end, then chat with DeDe about updating them in all of the shared Beats docs as well.
simitt
left a comment
simitt
left a comment
There was a problem hiding this comment.
Looks great, only left minor comments.
bmorelli25
force-pushed
the
revamp-apm-server-docs
branch
from
23b82f8 to
860696c
Compare
bmorelli25
force-pushed
the
revamp-apm-server-docs
branch
from
860696c to
4235252
Compare
# Conflicts: # docs/setting-up-and-running.asciidoc
# Conflicts: # docs/setting-up-and-running.asciidoc # Conflicts: # docs/copied-from-beats/command-reference.asciidoc
# Conflicts: # docs/setting-up-and-running.asciidoc # Conflicts: # docs/copied-from-beats/command-reference.asciidoc # Conflicts: # docs/setting-up-and-running.asciidoc
3 participants
You currently have to jump around a bit in order to get up and running with APM Server. This PR aims to rework the "Getting Started" and "Setting up and running" sections of the APM Server documentation to better guide users through the setup process. It also includes "cloud first" language.
Proposed new structure:
Important: I've temporarily set
:release-state:toreleasedfor conditional download sections to appear in the documentation preview. This must be reset tounreleasedbefore merging.