otel-tui

By default, otel-tui listens on the following ports:

• 4317: OpenTelemetry signals (gRPC)
• 4318: OpenTelemetry signals (HTTP)

Additional protocols can be enabled via flags:

• Zipkin (Traces): Port 9411 (requires --enable-zipkin)
• Datadog (Traces, Metrics): Port 8126 (requires --enable-datadog)
• DogStatsD (Metrics): Port 8125 (requires --enable-datadog)

Note: The server includes localhost in the Access-Control-Allow-Origin header, allowing telemetry to be sent directly from browser applications running on localhost.

You can install otel-tui using several methods depending on your environment:

Homebrew (macOS/Linux)

brew install ymtdzzz/tap/otel-tui

Go install

go install github.com/ymtdzzz/otel-tui@latest

Nix

nix develop github:ymtdzzz/otel-tui

Docker

Run the latest image directly:

docker run --rm -it --name otel-tui ymtdzzz/otel-tui:latest

GitHub Releases

Download the executable binary directly from the GitHub releases page.

The clipboard feature (triggered by the y key to copy log bodies) requires platform-specific tools to function.

• Linux/Unix: You must install xclip or xsel.
• macOS/Windows: No additional tools are required.

If these tools are not installed on Linux, the application will continue to run normally, but the clipboard functionality will be disabled.

The otel-tui collector supports Bearer token authentication for OTLP receivers (both HTTP and gRPC). You can provide this token via the AUTH_TOKEN environment variable.

export AUTH_TOKEN="your-bearer-token"
./otel-tui

The exporter implements the following methods to ingest telemetry data into the TUI store:

• pushTraces(ctx, traces): Adds ptrace.Traces to the TUI.
• pushMetrics(ctx, metrics): Adds pmetric.Metrics to the TUI.
• pushLogs(ctx, logs): Adds plog.Logs to the TUI.

func (e *tuiExporter) pushTraces(_ context.Context, traces ptrace.Traces) error
func (e *tuiExporter) pushMetrics(_ context.Context, metrics pmetric.Metrics) error
func (e *tuiExporter) pushLogs(_ context.Context, logs plog.Logs) error

The tuiexporter package provides a mechanism to export OpenTelemetry traces, metrics, and logs directly to a Terminal User Interface (TUI). It is designed to be used as a component within an OpenTelemetry Collector.

To use it, you must implement the standard exporter methods: pushTraces, pushMetrics, and pushLogs. These methods take OpenTelemetry data types (ptrace.Traces, pmetric.Metrics, and plog.Logs) and store them in the TUI's internal store for visualization.

The RenderYml() method allows you to generate a YAML configuration string by applying the current Config values to an internal template (config.yml.tpl). This is useful for exporting the current state of the configuration into a file format.

yamlString, err := cfg.RenderYml()
if err != nil {
    // handle error
}
fmt.Println(yamlString)

The Config struct defines the configuration parameters for the TUI exporter. It is compatible with the component.Config interface from the OpenTelemetry Collector.

Key configuration fields:

• FromJSONFile: A boolean flag (mapped from from_json_file) indicating if configuration should be loaded from a JSON file.
• DebugLogFilePath: A string (mapped from debug_log_file_path) specifying the file path where debug logs should be written.

type Config struct {
	FromJSONFile     bool   `mapstructure:"from_json_file"` 
	DebugLogFilePath string `mapstructure:"debug_log_file_path"` 
}

The runInteractive function initializes the otel-tui command with the provided otelcol.CollectorSettings and executes it. This starts the OpenTelemetry Collector with the integrated TUI (Terminal User Interface) viewer. The command is configured to handle OTLP HTTP and gRPC payloads, and can be customized via CLI flags.

err := runInteractive(params)
if err != nil {
	// handle error
}