Update examples in the Dynatrace documentation

[pirgeo]

This PR updates the documentation to include Spring Placeholder notation for the v2 exporter in order to make the setup process even easier.

[jonatan-ivanov]

@wilkinsona This is slightly related to the recent Dynatrace changes in Boot and Micrometer (that we released today). Do you think we can merge these doc improvements before 2.6.0-M2?

[snicoll]

Thanks for the PR but I am not keen to add additional information in the form of comments in the example without a good reason to.

If that's important, perhaps we should have two examples, each of them describing the differences in text rather than in the configuration itself. Please note that those comments are not rendered with the properties format.

The use of spring placeholder is not warranted IMO. It is a general feature that is applicable to any property.

[snicoll]

I am not keen to provide multiple options in the same example. These are not rendered for properties anyway and it feels like this is something that should be described rather than being put in the example directly.

[pirgeo]

The idea here was that users could just copy the example and remove the # for the option they want to use.

[snicoll]

OK but that doesn't address my previous comment.

[pirgeo]

Oh, I might have missed something here. Do I understand correctly that the comments within the code blocks will not show up in the documentation at all?

[pirgeo]

@snicoll, Is there something I missed here? Would you be able to provide some guidance on how to proceed?

[snicoll]

Do I understand correctly that the comments within the code blocks will not show up in the documentation at all?

There are not for properties. You can figure that out yourself by looking at the current documentation. We render the snippet in both yml and properties format. The latter doesn't have the comment. Ideally I'd like to rework those samples irrespective of this PR to remove the comment so I am not keen to add more comments.

Would you be able to provide some guidance on how to proceed?

From my perspective, it boils down to my first comment, specifically "it feels like this is something that should be described rather than being put in the example directly.". If we feel these are important enough examples to document, the different options should be described in text with some context, rather than in a comment of a snippet. I've flagged for team attention to get more feedback from the team.

[pirgeo]

In 57bd19f I moved the additional information to text paragraphs, either way is fine with me. The comments that still persist are optional, meaning that users that copy from the properties format still get the expected behavior, but in the yml format, they provide additional information.

[wilkinsona]

We should aim to treat users equally, irrespective of the format that they choose to use for configuration files. If the additional information is needed, I don't think it should be hidden in a comment that's only visible if you're using YAML.

[pirgeo]

@wilkinsona I have removed all comments, except for one that is only relevant for users of the YAML format. Thanks for explaining this, I did not realize that they would not show up in the properties file.

[snicoll]

I don't think this is warranted. Any property can be used with such a placeholder.

[pirgeo]

In some user's environments this particular property will already be populated. I didn't want to lay out in which cases this applies since that's subject to change and likely too detailed for these docs. How about this?

# If the DT_METRICS_INGEST_URL and DT_METRICS_INGEST_API_TOKEN are populated in your environment, you can use these with the Spring placeholder notation:
uri: ${DT_METRICS_INGEST_URL}
# should be read from a secure source and not hard-coded.
api-token: ${DT_METRICS_INGEST_API_TOKEN}

[wilkinsona]

should be read from a secure source and not hard-coded

I don't think this is necessary. There are numerous properties mentioned elsewhere in the documentation where this is the case and we don't have such a comment for each of them.

[snicoll]

Again, nothing particular about these properties.

[snicoll]

Thanks for the update. I am still not sure we should document the DT_METRICS_* properties. I don't know how and when it would apply to a user reading the doc...

[snicoll]

What does "depending on your setup" mean? I think that if something is setting those, perhaps we should link to whatever is setting them rather and put that doc there? I am mentioning this as I would prefer that our documentation does not provide too much information for something that would be better covered elsewhere anyway.

[pirgeo]

@snicoll I have removed the example for now since I don't have any good reference to put into the docs. Thanks for pointing out that that might be unclear for readers!