Package com.tnsai.quality.observability

Class SpanNaming

java.lang.Object
com.tnsai.quality.observability.SpanNaming
public final class SpanNaming extends Object
Canonical span-name and metric-name builder for TnsAI OpenTelemetry data.

All framework spans and metric counters use the form tnsai.<module>.<operation> — e.g. tnsai.agent.chat, tnsai.llm.stream, tnsai.tool.execute. Low-cardinality by design: providers, models, user IDs, tool names, and other variable values belong on span attributes, not in the span name. Names that carry cardinality break dashboards (one series per model) and alerting (can't group by provider without regex).

Usage


 Span span = tracer.spanBuilder(SpanNaming.of("agent", "chat"))
     .setAttribute("agent.id", id)
     .setAttribute("llm.provider", "openai")
     .setAttribute("llm.model", "gpt-4o")
     .startSpan();

Exception — provider-scoped LLM spans

LlmInstrumentation predates this convention and uses <provider>.<operation> <model> to preserve existing dashboards. New code should prefer SpanNaming.of("llm", "chat") with llm.provider / llm.model attributes.
Since:
0.3.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PREFIX
    Required prefix for every TnsAI-convention span / metric name.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    isCanonical(String name)
    Returns true if name matches the canonical form tnsai.<segment>.<segment>[.<segment>...].
    static String
    of(String module, String operation)
    Builds a canonical name tnsai.<module>.<operation>.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • PREFIX

      public static final String PREFIX
      Required prefix for every TnsAI-convention span / metric name.
      See Also:

  • Method Details

    • of

      public static String of(String module, String operation)
      Builds a canonical name tnsai.<module>.<operation>.

      Both segments are lower-cased (Locale.ROOT) and validated against SEGMENT. Upper-case input is tolerated and converted; whitespace, dots, or other punctuation fail fast so malformed names never reach the exporter.

      Parameters:
      module - short framework module identifier (e.g. "agent", "llm", "tool")
      operation - the verb being traced (e.g. "chat", "execute", "stream")
      Returns:
      canonical name in the form tnsai.<module>.<operation>
      Throws:
      IllegalArgumentException - if either segment is null, blank, or contains disallowed characters

    • isCanonical

      public static boolean isCanonical(String name)
      Returns true if name matches the canonical form tnsai.<segment>.<segment>[.<segment>...].

      Useful for test assertions and ArchUnit rules.

      Parameters:
      name - span or metric name to validate
      Returns:
      true when name follows the TnsAI convention