​
Semantic Conventions

This guide covers OpenTelemetry semantic conventions and how LangWatch implements them, along with our custom attributes for LLM-specific observability.

OpenTelemetry Standards

Understand the OpenTelemetry semantic conventions that LangWatch follows for consistent observability.

LangWatch Attributes

Explore LangWatch’s custom attributes designed specifically for LLM applications and AI observability.

​
What Are Semantic Conventions?

Semantic conventions are standardized naming and structure guidelines for observability data. They ensure consistency across different systems and make it easier to analyze and correlate data from various sources.
OpenTelemetry semantic conventions provide a standardized way to name attributes, events, and other observability data, making it easier to build tools and dashboards that work across different applications and services. For practical examples of these conventions in action, see Manual Instrumentation.

​
Benefits of Semantic Conventions

  • Consistency: Standardized naming across all your services
  • Interoperability: Works with any OpenTelemetry-compatible tool
  • Analytics: Easier to build dashboards and alerts
  • Debugging: Familiar patterns make troubleshooting faster
  • Team Collaboration: Shared understanding of observability data

​
OpenTelemetry Semantic Conventions

LangWatch fully implements OpenTelemetry semantic conventions, ensuring your traces are compatible with any OpenTelemetry-compatible observability platform.

​
Core Semantic Conventions

The OpenTelemetry specification defines conventions for common observability scenarios. LangWatch supports all OpenTelemetry semantic conventions while also providing its own custom attributes for LLM-specific observability. 
import * as semconv from "@opentelemetry/semantic-conventions";
// Or for bleeding edge attributes, you can import from the `incubating` module
import * as semconv from "@opentelemetry/semantic-conventions/incubating";

// Resource attributes (service information)
const resourceAttributes = {
  [semconv.ATTR_SERVICE_NAME]: "my-ai-service",
  [semconv.ATTR_SERVICE_VERSION]: "1.0.0",
  [semconv.ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: "production",
  [semconv.ATTR_HOST_NAME]: "server-01",
  [semconv.ATTR_PROCESS_PID]: process.pid,
};

​
Span Types and Attributes

OpenTelemetry defines standard span types and their associated attributes. LangWatch extends these with custom span types for LLM operations: 
// HTTP client span (OpenTelemetry standard)
span.setAttributes({
  "http.method": "GET",
  "http.url": "https://api.example.com/data",
  "http.status_code": 200,
  "http.request.header.user_agent": "MyApp/1.0",
});

// Database span (OpenTelemetry standard)
span.setAttributes({
  "db.system": "mysql",
  "db.name": "production_db",
  "db.operation": "INSERT",
  "db.statement": "INSERT INTO users (name, email) VALUES (?, ?)",
});

// LLM span (LangWatch custom)
span.setType("llm");
span.setAttributes({
  "langwatch.user.id": "user-123",
  "langwatch.thread.id": "thread-456",
  "langwatch.streaming": false,
});

​
TypeScript Autocomplete Support

All attribute setting methods in LangWatch provide full TypeScript autocomplete support, you don’t need to import anything, just use the attribute names directly and autocomplete will appear in your editor.

​
Autocomplete in Span Methods

import { getLangWatchTracer } from "langwatch";

const tracer = getLangWatchTracer("my-service");

await tracer.withActiveSpan("llm-operation", async (span) => {
  // TypeScript autocomplete works for all LangWatch attributes
  span.setAttributes({
    // Autocomplete shows all available attributes
    "code.function": "getLangWatchTracer",
    "langwatch.span.type": "llm",
    "langwatch.user.id": "user-123",
    "langwatch.thread.id": "thread-456",
    "langwatch.streaming": false,
    // ... more attributes with autocomplete
  });
});

​
Autocomplete in Configuration

import { setupObservability } from "langwatch/observability/node";
import { attributes } from "langwatch";

const handle = await setupObservability({
  serviceName: "my-service",
  attributes: {
    // Autocomplete shows all available LangWatch attributes
    "langwatch.sdk.version": "1.0.0",
    "langwatch.sdk.name": "langwatch-typescript",
    "langwatch.sdk.language": "typescript",
  }
});

​
LangWatch Attributes Reference

LangWatch provides a comprehensive set of custom attributes for LLM-specific observability. All attributes are available with TypeScript autocomplete support.

​
Core LangWatch Attributes

AttributeTypeDescriptionExample
langwatch.span.typestringType of span being traced"llm", "rag", "prompt"
langwatch.user.idstringUser identifier"user-123"
langwatch.thread.idstringConversation thread identifier"thread-456"
langwatch.customer.idstringCustomer identifier"customer-789"
langwatch.streamingbooleanWhether the operation involves streamingtrue, false
langwatch.inputstring/objectInput data for the span"Hello, how are you?"
langwatch.outputstring/objectOutput data from the span"I'm doing well, thank you!"
langwatch.contextsarrayRAG contexts for retrieval-augmented generationArray of document contexts
langwatch.tagsarrayTags for categorizing spans["chat", "greeting"]
langwatch.paramsobjectParameter data for operations{ temperature: 0.7 }
langwatch.metricsobjectCustom metrics data{ response_time: 1250 }
langwatch.timestampsobjectTiming information for events{ start: 1234567890 }
langwatch.evaluation.customobjectCustom evaluation data{ score: 0.95 }

​
SDK Information Attributes

AttributeTypeDescriptionExample
langwatch.sdk.namestringLangWatch SDK implementation name"langwatch-typescript"
langwatch.sdk.versionstringVersion of the LangWatch SDK"1.0.0"
langwatch.sdk.languagestringProgramming language of the SDK"typescript"

​
Prompt Management Attributes

AttributeTypeDescriptionExample
langwatch.prompt.idstringUnique prompt identifier"prompt-123"
langwatch.prompt.handlestringHuman-readable prompt handle"customer-support-greeting"
langwatch.prompt.version.idstringPrompt version identifier"version-456"
langwatch.prompt.version.numbernumberPrompt version number2
langwatch.prompt.selected.idstringSelected prompt from a set"selected-prompt-789"
langwatch.prompt.variablesobjectVariables used in prompt templates{ customer_name: "John" }

​
LangChain Integration Attributes

AttributeTypeDescriptionExample
langwatch.langchain.run.idstringLangChain run identifier"run-123"
langwatch.langchain.run.typestringType of LangChain run"chain", "tool"
langwatch.langchain.run.parent.idstringParent run identifier"parent-run-456"
langwatch.langchain.event_namestringLangChain event type"chain_start"
langwatch.langchain.run.metadataobjectRun metadata{ model: "gpt-5-mini" }
langwatch.langchain.run.extra_paramsobjectAdditional run parameters{ max_tokens: 1000 }
langwatch.langchain.run.tagsarrayRun-specific tags["production", "chain"]
langwatch.langchain.tagsarrayLangChain operation tags["langchain", "llm"]

​
Best Practices

​
Attribute Naming

Follow these conventions for consistent observability: 
// ✅ Good: Use LangWatch semantic convention attributes
span.setAttributes({
  "langwatch.span.type": "llm",
  "langwatch.user.id": "user-123",
  "langwatch.thread.id": "thread-456",
});

// ❌ Avoid: Custom attribute names without conventions
span.setAttributes({
  "span_type": "llm", // Use correct values or attributes.ATTR_LANGWATCH_SPAN_TYPE instead
  "user": "user-123", // Use correct values or attributes.ATTR_LANGWATCH_USER_ID instead
});

​
Attribute Values

Use appropriate data types and formats: 
// ✅ Good: Proper data types
span.setAttributes({
  "langwatch.streaming": false, // boolean
  "langwatch.user.id": "user-123", // string
  "langwatch.prompt.version.number": 2, // number
  "langwatch.tags": ["chat", "greeting"], // array
});

// ❌ Avoid: Inconsistent data types
span.setAttributes({
  "langwatch.streaming": "false", // string instead of boolean
  "langwatch.prompt.version.number": "2", // string instead of number
});

​
Sensitive Data

Never include sensitive information in attributes: 
// ✅ Good: Safe attributes
span.setAttributes({
  "langwatch.user.id": "user-123",
  "langwatch.span.type": "llm",
  "langwatch.sdk.version": "1.0.0",
});

// ❌ Avoid: Sensitive data in attributes
span.setAttributes({
  [attributes.ATTR_LANGWATCH_USER_ID]: "user-123",
  "api_key": "sk-...", // Never include API keys
  "password": "secret123", // Never include passwords
  "credit_card": "1234-5678-9012-3456", // Never include PII
});

​
Performance Considerations

Limit the number and size of attributes for performance:
✅ Good❌ AvoidReason
4-8 attributes per span50+ attributesToo many impacts performance
Short string valuesLarge text contentUse span.setInput() for large content
Structured dataNested objectsKeep attributes simple
Essential metadataRedundant informationOnly include what’s needed

​
Summary

Semantic conventions provide a standardized approach to observability data that:
  • Ensures consistency across your entire application
  • Enables interoperability with OpenTelemetry-compatible tools
  • Improves debugging with familiar patterns
  • Supports team collaboration with shared understanding
LangWatch implements both OpenTelemetry semantic conventions and custom LLM-specific attributes, all with full TypeScript autocomplete support to help you use the right attributes consistently.
Key takeaways:
  • Use semantic convention attributes for consistency
  • Import attributes from LangWatch for autocomplete
  • Follow OpenTelemetry standards for interoperability
  • Leverage LangWatch’s LLM-specific attributes for AI observability
For practical examples and advanced usage patterns:
Use semantic conventions consistently across your application for better analytics, debugging, and team collaboration. Start with the Manual Instrumentation tutorial to see these conventions in practice.