docs: update docs for the GA

[theletterf]

• Create a docs folder. Inside there should be:

  • A page with all configuration settings relevant to our distro; separate them from the README if they're all there already (see https://github.com/signalfx/splunk-otel-java/blob/main/docs/advanced-config.md)
  • Are all settings configured via ENV vars? Or is there a runtime argument way, too, as with Java? Let's specify all ways of config, which is preferred, and why
  • Instructions on how to correlate traces with logs, if that's possible (or a link to OTel docs on how to do that)
  • A list of supported libraries and frameworks, or links to that info (see https://github.com/signalfx/splunk-otel-java/blob/main/docs/supported-libraries.md)
  • Basic troubleshooting doc with things like enabling debug logging (see https://docs.splunk.com/Observability/gdi/get-data-in/application/java/troubleshooting/common-java-troubleshooting.html#nav-Troubleshooting)

Additionally:

• VERSIONING.md file explaining how release happen (see https://github.com/signalfx/splunk-otel-java/blob/main/VERSIONING.md)
• Clarify what features make our distro stand out compared to upstream?
• What are instrumentation plugins for? Can we present a use case?
• Remove SPLUNK_MAX_ATTR_LENGTH. Prefer the native OTel env vars instead which will be soon merged in upstream.

[codecov-commenter]

Codecov Report

Merging #279 (f250b34) into main (6dda2ad) will not change coverage.
The diff coverage is n/a.

❗ Current head f250b34 differs from pull request most recent head 39eff16. Consider uploading reports for the commit 39eff16 to get more accurate results

@@           Coverage Diff           @@
##             main     #279   +/-   ##
=======================================
  Coverage   94.89%   94.89%           
=======================================
  Files          10       10           
  Lines         294      294           
  Branches       75       75           
=======================================
  Hits          279      279           
  Misses         15       15           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6dda2ad...39eff16. Read the comment docs.

[rauno56]

A page with all configuration settings relevant to our distro

All the current options are defined in README. See it in the code here: https://github.com/signalfx/splunk-otel-js/blob/main/src/options.ts#L49-L61 to double-check.

Are all settings configured via ENV vars? Or is there a runtime argument way, too, as with Java? Let's specify all ways of config, which is preferred, and why

Most of the settings have both. The difference is only in options that do not make sense as an env var - when the thing you need to provide is a function or an object. process.env.* is the node way of accessing the environment <- a way to double-check that we've covered everything.

There's no preferred way I'd say. Env is easier to get off the ground with. The programmatic way gives you better control. I'd say it's always better to go with former as long as it's sufficient for your usecase.

Instructions on how to correlate traces with logs, if that's possible (or a link to OTel docs on how to do that)

We auto-instrument popular logging libs, but you have to use one of those to get the correlation - which kinda makes sense, there's no reasonable way to know you're logging to stdout without those. The config options are documented, but no deeper context is given - we expect the user to know what "log injection" means and does. There are also tests for those that might give you an idea how they work and what do expect.

A list of supported libraries and frameworks

There's a list in the readme. Incomplete one though because we support everything that's officially supported by OTel and that list is constantly growing. See opentelemetry-instrumentation-* folders here + the OTel registry.

Basic troubleshooting doc with things like enabling debug logging

Enabling diagnostics logging is shown in the express example.

VERSIONING.md file explaining how release happen

We have https://github.com/signalfx/splunk-otel-js/blob/main/RELEASING.md.

Clarify what features make our distro stand out compared to upstream

• We make it trivial to connect to Splunk's backends(wow, right?);
• Auto-load installed instrumentations;
• Bundle and configure best practices out of the box.
• Are ~80%* interoperable with standard OTel. See Use the standard OTel Node SDK #266

* I made this number up.

What are instrumentation plugins for? Can we present a use case?

Just like for any other language distro they are an automatic way to generate library-specific spans. They give insight into the usage of the instrumented library with virtually 0 effort! See the examples.

[theletterf]

@rauno56 For GA, I think that the only docs that you need is adding a Troubleshooting section the README, which would benefit me greatly, too. Following what Python and Java did, I suggest that you also add a section on correlating traces and logs. For example, see https://github.com/signalfx/splunk-otel-java/blob/main/docs/correlating-traces-with-logs.md

I believe it is a requirement also to document all settings/config params: https://github.com/signalfx/gdi-specification/blob/main/specification/repository.md#data-collector. An example you'd follow is what the Java team did, with ENV vars and their runtime equivalents: https://github.com/signalfx/splunk-otel-java/blob/main/docs/advanced-config.md

Those pieces I can review and help improve, but the raw input to the repo must come from you. (I'd try and build the tables of settings based on what's in the README, but I might miss something. In any case, you should pull the settings from there and put them in a separate page.)

How does the above sound?