Add Language Library Design Principles

[tigrannajaryan]

These principles provide common ground for understanding what
are requirements for a language library API and provides guidelines
for language library authors.

This is co-authored by me and @bogdandrutu

[tigrannajaryan]

It is best to start reviewing using raw view so that you see the diagram: https://github.com/open-telemetry/opentelemetry-specification/blob/e77bb77b2d2e726c8785d0fb77efc6e7fe37d7d5/specification/library-guidelines.md

[SergeyKanzhelev]

we discussed that for mocking purposes it's better to use SDK with the mock exporter or processor. This way an actual logic will be tested. Should we encourage this use case at all?

[austinlparker]

+1 to mock exporter with SDK, this is the model we used in OT. That said, I think it'll be incumbent on anyone doing a replacement implementation to provide their own mock.

[tigrannajaryan]

I thought about making the mock just another exporter but I think there are certain benefits for replacing the entire SDK with a mock implementation.

The SDK as we envision it may be too thick for simple mocking. Why do I need batching, tagging and all things that SDK does by default in a mock? When I use a mock in my automated tests I do not intend to verify how SDK does its job, I intend to verify if my instrumented code is calling telemetry API correctly. All I care about in the mock is to be able to inspect the results of telemetry calls.

The SDK's internal logic can be a detriment to my testing goals. For example if it batches and reorganizes telemetry data it may make inspection of data more difficult in the tests. This unneeded logic will also impose a small performance penalty on automated tests.

I think there are probably valid use cases for both approaches. The mocking by replacing only the exporter can be better suited for broader automated tests that are closer to integration tests or end-to-end tests.

[austinlparker]

How much of an overhead do we really think there will be? I got my terms mixed up earlier - we provide a mock tracer in OT, rather than a mock exporter as there's no exporter concept there - but it seems like a mock exporter is going to be easier for third parties to implement. Moreover, it seems like it'd be valuable to be able to understand the performance overhead of the SDK on the application code.

[tigrannajaryan]

@austinlparker you are right that likely the performance overhead is going to be minimal. The unnecessary complication of tests may be non-trivial though.

Think about how you would test if the mock is a full SDK with a mock Exporter.

Your test executes a function that calls telemetry API. This in turn ends up in the SDK which decides to do batching and does NOT call the mock Exporter immediately. The SDK calls the mock Exporter after some timeout that is part of batching logic.

Now your test has to asynchronously wait for SDK batching logic timeout. This complicates the test, makes it potentially much slower and also makes it be aware of internal implementation details of the SDK, particularly that there is a batching logic with timeout.

I can envision other troubles as well. E.g. what if batching also reorders data for efficiency purposes? Now I need special logic in my test to find the telemetry data that I am looking for rather than be sure that the first data I see is what I need.

[SergeyKanzhelev]

CC: @mtwo for language clean up and suggestions on "glossary"

[tigrannajaryan]

Reviewers, I pushed an update, please have another look.

Open questions:

1. Are exporters part of SDK or they are separate packages and should be shown outside of SDK on the diagrams?
2. Are we OK with 2 different ways of mocking possible?

[tigrannajaryan]

@SergeyKanzhelev do you have more comments or we can merge this?

[reyang]

LGTM.

[SergeyKanzhelev]

I liked the mention you had before about alternative data models. Like event-based, not span-based backends. Alternative Tracer would be most useful in such examples.

[SergeyKanzhelev]

I believe there is a room for improvements. For example, better explain what is expected from the box products that exposes telemetrey.

It is a very important document. And this is a solid staring point. Thank you!

[tigrannajaryan]

@SergeyKanzhelev sounds good, we can keep improving it in new PRs.
Can you merge this? I don't have merging rights.

[mtwo]

LGTM pending some minor comments

[mtwo]

@SergeyKanzhelev how do we distinguish between "default" (context propagation) and "default" (full standard implementation)?

[mtwo]

My understanding is that we'll include Zipkin, Jaeger, and Prometheus out of the box ... all others will need to be linked