Package io.micrometer.tracing.docs

Interface SpanDocumentation

public interface SpanDocumentation
In order to describe your spans via e.g. enums instead of Strings you can use this interface that returns all the characteristics of a span. In Micrometer Tracing we analyze the sources and reuse this information to build a table of known spans, their names, tags and events.

We can generate documentation for all created spans but certain requirements need to be met

  • Metrics are grouped within an enum - the enum implements the SpanDocumentation interface
  • If the span contains KeyName then those need to be declared as nested enums
  • If the span contains EventValue then those need to be declared as nested enums
  • The getKeyNames() need to call the nested enum's values() method to retrieve the array of allowed keys
  • The getEvents() need to call the nested enum's values() method to retrieve the array of allowed events
  • Javadocs around enums will be used as description
Since:
1.0.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final io.micrometer.common.docs.KeyName[]
    EMPTY_KEY_NAMES
    Empty key names.
    static final EventValue[]
    EMPTY_VALUES
    Empty values.

  • Method Summary

    Modifier and Type
    Method
    Description
    default io.micrometer.common.docs.KeyName[]
    getAdditionalKeyNames()
    Additional key names.
    default EventValue[]
    getEvents()
    Allowed events.
    default io.micrometer.common.docs.KeyName[]
    getKeyNames()
    Allowed key names.
    String
    getName()
    Span name.
    default String
    getName(String... vars)
    Builds a name from provided vars.
    default String
    getPrefix()
    Returns required prefix to be there for tags.
    default Enum<?>
    overridesDefaultSpanFrom()
    Override this when custom span should be documented instead of the default one.

  • Field Details

    • EMPTY_KEY_NAMES

      static final io.micrometer.common.docs.KeyName[] EMPTY_KEY_NAMES
      Empty key names.

    • EMPTY_VALUES

      static final EventValue[] EMPTY_VALUES
      Empty values.

  • Method Details

    • getName

      String getName()
      Span name.
      Returns:
      metric name

    • getName

      default String getName(String... vars)
      Builds a name from provided vars. Follows the String.format(String, Object...) patterns.
      Parameters:
      vars - variables to pass to String.format(String, Object...)
      Returns:
      constructed name

    • getEvents

      default EventValue[] getEvents()
      Allowed events.
      Returns:
      allowed events

    • getKeyNames

      default io.micrometer.common.docs.KeyName[] getKeyNames()
      Allowed key names.
      Returns:
      allowed key names - if set will override any key names coming from overridesDefaultSpanFrom()

    • getAdditionalKeyNames

      default io.micrometer.common.docs.KeyName[] getAdditionalKeyNames()
      Additional key names.
      Returns:
      additional key names - if set will append any key names coming from overridesDefaultSpanFrom()

    • overridesDefaultSpanFrom

      default Enum<?> overridesDefaultSpanFrom()
      Override this when custom span should be documented instead of the default one.
      Returns:
      ObservationDocumentation for which you don't want to create a default span documentation

    • getPrefix

      default String getPrefix()
      Returns required prefix to be there for tags. For example, foo. would require the tags to have a foo. prefix like this: foo.bar=true.
      Returns:
      required prefix