Skip to content
This repository has been archived by the owner on Dec 6, 2024. It is now read-only.

RFC for "greybox" instrumentation that's magical but not manual #7

Closed

Conversation

lizthegrey
Copy link
Member

@lizthegrey lizthegrey commented Jul 11, 2019

It would be a degradation in customer experience for Honeycomb to recommend OpenTelemetry as the default installation/instrumentation path for our customers until there's feature parity with our own vendor-specific (but Apache-licensed) Beelines which provide automatic instrumentation in <50 lines of code modification for new users.

Thus, we'd like to contribute our Beelines to the community so we can focus on integrations work entirely between OTel and the Honeycomb exporter instead of maintaining disjoint end to end integrations :)

@lizthegrey lizthegrey changed the title Create 0003-automatic-telemetry-libraries RFC for "greybox" instrumentation that's magical but not manual Jul 11, 2019
@yurishkuro
Copy link
Member

I feel this is the same as the "zero-touch" instrumentation RFC #5. Whether it requires a single line of code change or appending a jar to the classpath is more of a language-specific implementation detail.

@lizthegrey
Copy link
Member Author

However, rfc #5 says "no code changes may be made", it must be "zero touch" (e.g. because we don't even have the source code or ability to change it)... which rules out this approach. So, we should either hold off on merging #5 and address this use case in it, or we should consider #7 independently as a separate use case.

@lizthegrey
Copy link
Member Author

lizthegrey commented Jul 11, 2019

Answering @bhs's question from the other thread: the design philosophy behind beelines is 100% aligned with the trace and span model -- it's about automatically creating traces and spans using incoming/outgoing HTTP requests, gRPC requests, and downstream calls to databases etc.

@maplebed can say more about our original goals as he's been around Honeycomb longer than I have.

@yurishkuro
Copy link
Member

yurishkuro commented Jul 12, 2019

@lizthegrey I agree, I added comment to relax the wording a bit.

@tsloughter
Copy link
Member

These (the linked to beelines) look like the way OpenCensus creates integrations, see https://opencensus.io/integrations/ and https://opencensus.io/guides/http/

If the RFC is meant to codify that process I think it should mention cross language specifications for the data recorded in the provided instrumentations. For example all the OpenCensus HTTP libs follow https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md

@lizthegrey
Copy link
Member Author

100% agreed that common fields and terminology are essential :)

@@ -0,0 +1,66 @@
# Automatic language/framework instrumentation in OpenTelemetry

_Cross-language requirements for automatically extracting portable telemetry data with minimal ("greybox") source code modification._
Copy link
Member

Choose a reason for hiding this comment

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

I'm very on board with minimal, "greybox" implementation. However, I think using the word "automatic" is confusing: it implies zero-touch, rather than low-touch.

### Requirements

Without further ado, here are a set of requirements for “official” OpenTelemetry efforts to accomplish greybox minimal-source-code-modification instrumentation (i.e., “OpenTelemetry framework adapters”) in any given language:
* No more than 50 lines of _manual_ source code modifications allowed regardless of the number of handlers/frameworks in use
Copy link
Member

Choose a reason for hiding this comment

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

I'm wondering about how to frame this in a way that's not about number of lines of code, which feels like a proxy that may become overly restrictive - I can see some weird code reviews coming up in the future.


Without further ado, here are a set of requirements for “official” OpenTelemetry efforts to accomplish greybox minimal-source-code-modification instrumentation (i.e., “OpenTelemetry framework adapters”) in any given language:
* No more than 50 lines of _manual_ source code modifications allowed regardless of the number of handlers/frameworks in use
* Licensing must be permissive (e.g., ASL / BSD)
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
* Licensing must be permissive (e.g., ASL / BSD)
* Licensing must follow CNCF licensing rules (i.e., ASL / BSD)

I believe that CNCF only allows ASL and BSD?

Without further ado, here are a set of requirements for “official” OpenTelemetry efforts to accomplish greybox minimal-source-code-modification instrumentation (i.e., “OpenTelemetry framework adapters”) in any given language:
* No more than 50 lines of _manual_ source code modifications allowed regardless of the number of handlers/frameworks in use
* Licensing must be permissive (e.g., ASL / BSD)
* Packaging must allow vendors to “wrap” or repackage the portable (OpenTelemetry) library into a single asset that’s delivered to customers
Copy link
Member

Choose a reason for hiding this comment

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

For languages where zero-touch (#5) is feasible, zero-touch should probably be a wrapper of the low-touch libraries. Thoughts on whether it would make sense to support a canonical, OpenTelemetry wrapper, which is what vendors are then recommended to support? (I might also be misunderstanding this point!)

* Licensing must be permissive (e.g., ASL / BSD)
* Packaging must allow vendors to “wrap” or repackage the portable (OpenTelemetry) library into a single asset that’s delivered to customers
* That is, vendors do not want to require users to comprehend both an OpenTelemetry package and a vendor-specific package
* "Greybox" OpenTelemetry framework adapters must interoperate with both explicit, whitebox OpenTelemetry instrumentation and the “automatic” / zero-source-code-modification / blackbox instrumentation proposed in RFC 0002.
Copy link
Member

Choose a reason for hiding this comment

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

Per above, this seems reversed to me - i.e., it feels like zero-touch should be built on top of low-touch, rather than low-touch on top of zero-touch.

@bhs
Copy link
Contributor

bhs commented Aug 4, 2019

@lizthegrey I'm going through RFC PRs and realized this one is in an ambiguous state.

IMO it is confusing/ambiguous for OpenTel to have both a blackbox and "greybox" RFC out, especially at this early stage of the project. All other things being equal, blackbox is easier for end-users and thus seems preferable. Of course all other things are not always equal, hence the rationale for this RFC.

That said, I'm wondering if we can make changes to the existing blackbox RFC to cover more of the nuance here (rather than creating this separate, highly-overlapping RFC). I am imagining something explaining what the priority order is for "low-touch" OpenTel instrumentation on a per-language basis.

WDYT?

@lizthegrey
Copy link
Member Author

I agree that merging this with the existing blackbox RFC is probably better as a structural approach.

@lizthegrey
Copy link
Member Author

Going to close this one out and instead propose a change to the existing 0-touch RFC.

@lizthegrey lizthegrey closed this Aug 28, 2019
@lizthegrey
Copy link
Member Author

Because we're adopting Datadog's approach, this is now indeed de-facto what we're doing :)

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

Successfully merging this pull request may close these issues.

5 participants