Snippets

[jack-berg]

First take on #393.

Details:

• Introduces a new /snippets directly with files named <JsonSchemaType>_<snake_case_snippet_description>.yaml
• Each file is a fully valid OpenTelemetryConfiguration type, but is meant to emphasize a particular snippet of a specific type, indicated by the <JsonSchemaType> in the file naming convention
• A new task make validate-snippets validates each snippet file against OpenTelemetryConfiguration, and the snippet being emphasized (as indicated by # SNIPPET_START) against its corresponding JSON schema type
• Snippets may include comments which describe a very narrow use case being demonstrated.
• The make generate-markdown task outputs snippets in schema-docs.md. For example, I've added a snippet demonstrating how to use a view to change the default histogram bucket boundaries for a specific instrument via a view. See screenshot below, or generated markdown here:

If we like this direction, we can open followup PRs which chip away at kitchen-sink.yaml, and delete it.

[jack-berg]

TODO: add documentation before merging

[marcalff]

I can see how having just a code fragment (snippet) is useful for the documentation.

The downside is that this fragment can no longer be used as a stand alone test.

Could the snippet file format be extended for example like this:

file_format: "1.0-rc2"

meter_provider:
  readers:
    periodic:
      exporter:
        otlp_http:
# === SNIPPET START HERE ===
          endpoint: http://localhost:4318/v1/metrics
          default_histogram_aggregation: base2_exponential_bucket_histogram
# === SNIPPET ENDS HERE ===

Assuming the tooling can extract the snippet, this will allow:

• to validate the entire document, instead of finding the node name and validate against the node schema only
• to reuse this full configuration file as stress test.

Each SDK implementation will gain a lot if running tests straight from the configuration repository, to make sure the SDK code does not diverge from the schema over time.

[jack-berg]

The downside is that this fragment can no longer be used as a stand alone test.

@marcalff for java, I was imagining building a test harness which:

• Iterated through all snippets
• Parsed the snippet file name to extract the expected type
• Find the "factory" (a java implementation concept in which we have a roughly 1:1 mapping between JSON schema types and factories in this package)
• Parse the snippet YAML, and run it through the matched factory

Could the snippet file format be extended for example like this:

Yes that's possible too. Its more verbose of course, which is the downside.

But the upside is that when rendering the snippet in the docs, we could optionally render the entire document with the embedded snippet, which would probably help make it more obvious where the type is actually used.

[jack-berg]

@marcalff I've come around to the approach you've suggested, pushed a commit reflecting it, and updated the PR description.

A typical snippet now looks like:

File contents at ./snippets/Sampler_parent_based.yaml:

file_format: "1.0-rc.2"

tracer_provider:
  processors:
    - simple:
        exporter:
          console:
  # SNIPPET_START
  sampler:
    parent_based:
      root:
        trace_id_ratio_based:
          ratio: 0.0001
      remote_parent_sampled:
        always_on:
      remote_parent_not_sampled:
        probability/development:
          ratio: 0.01
      local_parent_sampled:
        always_on:
      local_parent_not_sampled:
        always_off:

• The build tooling will validate the entire file contents against the root OpenTelemetryConfiguration type. This means we often have to include some irrelevant extra bits to pass validation (e.g. .tracer_provider.processors here). But in exchange, implementations can now easily use the directly of snippets as tests.
• The file is named _<snake_case_description>`, so for this example:
  • JSON schema type: Sampler
  • Description (converted to title case): Parent Based
• The # SNIPPET_START indicates the start of the point of interest. The tooling will:
  • Identify this and for all the lines after it, strip whitespace equivalent to what proceeds # SNIPPET_START (in this case, two spaces will be stripped from following lines)
  • Take the resulting blob of content, and validate it against <JsonSchemaType> from the file name
• Markdown generation includes the portion after # SNIPPET_START, and provides a link back to the snippet source file so users can see the snippet in the context of the larger schema.

Pretty cool, I think. Should be very useful for users and maintainers alike.

[marcalff]

LGTM, this will be very useful.