Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize autoconfigure docs by signal #5665

Merged
merged 1 commit into from
Aug 3, 2023

Conversation

jack-berg
Copy link
Member

Was having a hard time navigating the autoconfigure docs the other day because the's not a lot of organization.

This reorganizes it into sections for each signal provider (tracer provider, meter provider, logger provider) which contain configuration related to that specific signal, and a general configuration section containing signal agnostic options (exporters, resource, attribute limits, propagator).

Also generates the TOC with markdown-doc, which is what the specification uses. Didn't want to be heavy handed and introduce a bunch of automation / checking, so I just added a comment with instructions.

@jack-berg jack-berg requested a review from a team July 31, 2023 21:04
@codecov
Copy link

codecov bot commented Jul 31, 2023

Codecov Report

Patch coverage has no change and project coverage change: +0.02% 🎉

Comparison is base (9ea8324) 91.29% compared to head (e8738ba) 91.31%.
Report is 1 commits behind head on main.

Additional details and impacted files
@@             Coverage Diff              @@
##               main    #5665      +/-   ##
============================================
+ Coverage     91.29%   91.31%   +0.02%     
  Complexity     4978     4978              
============================================
  Files           554      554              
  Lines         14731    14731              
  Branches       1376     1376              
============================================
+ Hits          13448    13451       +3     
+ Misses          887      884       -3     
  Partials        396      396              

see 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Copy link
Member

@mateuszrzeszutek mateuszrzeszutek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice 👍
Do you think we could move this to the opentelemetry.io page at some point?

@trask
Copy link
Member

trask commented Aug 1, 2023

Nice 👍 Do you think we could move this to the opentelemetry.io page at some point?

cc @open-telemetry/docs-maintainers

@jack-berg
Copy link
Member Author

Nice 👍
Do you think we could move this to the opentelemetry.io page at some point?

Yeah I'm in favor of that if the @open-telemetry/docs-maintainers agree.

@cartermp
Copy link

cartermp commented Aug 2, 2023

Yeah, this would be great to have in docs. I'm fine with whatever process works best for you (merge here, move over, just re-add it over in docs, or something else).

@svrnm
Copy link
Member

svrnm commented Aug 2, 2023

Yeah, this would be great to have in docs. I'm fine with whatever process works best for you (merge here, move over, just re-add it over in docs, or something else).

+1

@jack-berg jack-berg merged commit a9b285d into open-telemetry:main Aug 3, 2023
@chalin
Copy link
Contributor

chalin commented Aug 3, 2023

Where would you want the past hosted on the website?

@jack-berg
Copy link
Member Author

@chalin There's a small section dedicated to autoconfiguration on the Instrumentation > Java > Manual. We could split out a page dedicated to autoconfiguration, or expand the existing section on the Manual page.

WDYT?

@svrnm
Copy link
Member

svrnm commented Aug 4, 2023

@jack-berg We also have a reference to the autoconfiguration here:

https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/

Just for my understanding: the Javaagent makes use of the SDK Autoconfiguration, but it can also be used in combination with manual instrumentation?

It sounds to me that it lives somewhere between manual and automatic instrumentation then (a thing we see with other languages emerging as well, e.g. sdk-node seems to live in a similar space)

Is using Auto Configuration the preferred way of doing things or should manual creation of the OpenTelemetry instance be what people default to? If so, maybe we should lead with it in the Manual Instrumentation doc?

@jack-berg
Copy link
Member Author

the Javaagent makes use of the SDK Autoconfiguration, but it can also be used in combination with manual instrumentation?

Correct.

It sounds to me that it lives somewhere between manual and automatic instrumentation then (a thing we see with other languages emerging as well, e.g. sdk-node seems to live in a similar space)

That makes sense to me, especially since the agent makes reference to the section.

Is using Auto Configuration the preferred way of doing things or should manual creation of the OpenTelemetry instance be what people default to? If so, maybe we should lead with it in the Manual Instrumentation doc?

Auto Configuration is preferred. Its always been easier than programatic configuration but was hard to recommend since it was unstable until the July 1.28.0 release. Now that its stable, its the clear winner. Along with interpreting all the standard environment variables, it has various customization capabilities which allow you to do things like reference custom extension components like exporters in environment variables, and layer programmatic configuration on top of the standard environment variable. Eventually, autoconfigure will also be able to interpret configuration files in the schema described in opentelemetry-configuration. I'm sure there are use cases out there for programmatic configuration, but they're becoming increasingly rare.

@svrnm
Copy link
Member

svrnm commented Aug 7, 2023

thanks @jack-berg!

I was planning to go over the Manual Instrumentation for Java and improve it in the same way as the one for JavaScript, so I'll see that I promote Auto Configuration accordingly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants