Use appropriate reserved domain for example URLs

[ebeahan]

Summary

Two minor documentation changes for the event.* field set:

• Removed the "live" URL links by adding quotes to the string. This is actually incorrect. Our documentation generator is handling this by always wrapping example strings with backticks (`). As long as we ensure the examples don't use potentially valid domains, I don't think we need to worry about being "defensive" for other doc locations which may render a hyperlink for the URLs (e.g. Beats).

• Switched example URLs to use the IANA reserved *.example.com

[webmat]

LGTM

Have you looked at some of the other places where they may show up, like url and source/dest/client/server?

[ebeahan]

I noted the other places using real domains:

Field(s)	Example Value
*.registered_domain	www.google.com
package.reference	https://golang.org
tls.client.server_name, url.domain	www.elastic.co
x509.issuer.organizational_unit	www.digicert.com
x509.subject.common_name	r2.shared.global.fastly.net
x509.subject.distinguished_name	C=US, ST=California, L=San Francisco, O=Fastly, Inc., CN=r2.shared.global.fastly.net

While it's top of mind, should we unify all of our example usages to example.com for uniformity? ♻️

[webmat]

Yeah if you're up for it 👍

I guess we may have to make a few adjustments outside of these domains per se, for the examples to continue making sense. Example for x509.subject.distinguished_name:

C=US, ST=California, L=San Francisco, O=Example, Inc., CN=certs.example.com

Out of the ones you've outlined, I think I would leave package.reference at "https://golang.org". I think this one is important at conveying that we're not looking for a download link, but more of a documentation page or the home of whatever software is in the package.

[webmat]

Whenever you work on some of these domains, make sure to adjust the domain breakdowns as well. www.example.com => .registered_domain: example.com, .top_level_domain: com

[ebeahan]

@webmat this is ready for another 👀

Should we plan on backporting these changes to 1.5?

[webmat]

I think the only remaining domain we could adjust is on server.subject, where we have "www.mydomain.com". Could you adjust it as well in the same way?

Yeah I think it makes sense to backport this to 1.5. Note that if Beats wants to reimport our field defs to adjust some of the examples that come from ECS, we'd have to cut 1.5.1. But unless this is clearly needed, I think we can simply backport to 1.5 for now, and at least have the main docs corrected.

[webmat]

LGTM