Quick Start

Architecture

Demo Composer

• docker-compose.example.yml
• Client 会生成 traceID。
• 通过 HTTP 的 Header 把 traceID 带给 Server。
• Client 和 Server 都会把 span 数据上报到 OTEL Collector。

graph LR
    subgraph "example.yml"
        D2[Demo Client] -->|OTLP/gRPC| F2[OTEL Collector]
        E2[Demo Server] -->|OTLP/gRPC| F2
        D2 -->|HTTP 请求| E2
        F2 -->|Export| G2[teletrace-api]
    end

    classDef collector fill:#f96,stroke:#333,stroke-width:2px
    classDef api fill:#9cf,stroke:#333,stroke-width:2px
    classDef demo fill:#bbf,stroke:#333,stroke-width:1px

    class F2 collector
    class G2 api
    class D2,E2 demo

+-------------+     HTTP 请求     +-------------+
| Demo Client |----------------->| Demo Server |
|             |                  |             |
+-------------+                  +-------------+
       |                               |
       |                               |
       | OTLP/gRPC                     | OTLP/gRPC
       |                               |
       v                               v
+------------------------------------------+
|             OTEL Collector               |
+------------------------------------------+
                   |
                   | Export
                   v
+------------------------------------------+
|             teletrace-api                |
+------------------------------------------+

SQLite Mode

• docker-compose-.sqlite.yml
• 内部 OTEL Collector 会接收外部 OTEL Collector 的数据（由 Client 和 Server 上报）。
• 内部 OTEL Collector 在启动时会通过 //go:embed migrations 创建表。

graph TD
    subgraph "SQLite 模式"
        subgraph "teletrace-api 容器"
            A1[内部 OTEL Collector<br>端口 4317/4318] -->|存储| B1[(SQLite<br>embedded_spans.db)]
            C1[Teletrace API<br>端口 8080] -->|查询| B1
        end
        
        D1[外部 OTEL Collector] -->|OTLP/gRPC| A1
    end

    classDef collector fill:#f96,stroke:#333,stroke-width:2px
    classDef api fill:#9cf,stroke:#333,stroke-width:2px
    classDef storage fill:#9f9,stroke:#333,stroke-width:2px
    classDef demo fill:#bbf,stroke:#333,stroke-width:1px

    class A1 collector
    class C1 api
    class B1 storage
    class D1 demo

+--------------------------------------------------+
|                   SQLite 模式                      |
|                                                  |
|   +------------------------------------------+   |
|   |           teletrace-api 容器              |   |
|   |                                          |   |
|   |  +---------------+      +-------------+  |   |
|   |  | 内部 OTEL     |      |   SQLite     |  |   |
|   |  | Collector     |---->| embedded_    |  |   |
|   |  | 端口4317/4318 | 存储 | spans.db     |  |   |
|   |  +---------------+      +-------------+  |   |
|   |         ^                     ^         |   |
|   |         |                     |         |   |
|   |         |                     | 查询    |   |
|   |         |              +-------------+  |   |
|   |         |              | Teletrace   |  |   |
|   |         |              | API         |  |   |
|   |         |              | 端口 8080   |  |   |
|   |         |              +-------------+  |   |
|   +---------|--------------------------|----+   |
|             |                          |        |
| +---------------+                               |
| | 外部 OTEL     |                               |
| | Collector    |                               |
| +--------------+                               |
|                                                |
+------------------------------------------------+

Run with SQLite

cd deploy/docker-compose

cp ../../teletrace-otelcol/config/all-in-one-config.yaml .

docker compose -f docker-compose.sqlite.yml up

The following cmd will use es storage.

 docker run \
    -v $(pwd)/all-in-one-config.yaml:/etc/config.yaml \
    -p 8080:8080 \
    -p 4317:4317 \
    -p 4318:4318 \
    --name teletrace-api \
    teletrace/teletrace:latest \
    --config /etc/config.yaml

Example Data

Build Client & Server

export OTEL_COLLECTOR_VERSION=0.64.1 && docker-compose -f docker-compose.example.yml up

export OTEL_COLLECTOR_VERSION=0.64.1 && docker-compose -f docker-compose.example.yml up --build

SQLite

Find .db File

docker exec -it teletrace-api sh -c "find / -name 'embedded_spans.db' 2>/dev/null"

Copy .db File

docker cp teletrace-api:/app/embedded_spans.db ./

Access DB

sqlite3 embedded_spans.db

Show Tables

.tables

event_attributes          resource_attributes       span_attributes
events                    schema_migrations         span_resource_attributes
link_attributes           scope_attributes          spans
links                     scopes

Schema Spans

.schema spans

CREATE TABLE spans (
     span_id TEXT PRIMARY KEY,
     trace_id TEXT NOT NULL,
     trace_state TEXT,
     parent_span_id TEXT,
     name TEXT,
     kind TEXT,
     start_time_unix_nano INTEGER NOT NULL,
     end_time_unix_nano INTEGER NOT NULL,
     dropped_span_attributes_count INTEGER NOT NULL,
     span_status_message TEXT NOT NULL,
     span_status_code TEXT NOT NULL,
     dropped_resource_attributes_count INTEGER NOT NULL,
     dropped_events_count INTEGER NOT NULL,
     dropped_links_count INTEGER NOT NULL,
     duration INTEGER NOT NULL,
     ingestion_time_unix_nano INTEGER NOT NULL,
     instrumentation_scope_id INTEGER NOT NULL,
     FOREIGN KEY(instrumentation_scope_id) REFERENCES scopes(id)
);
CREATE INDEX start_time_index
ON spans (start_time_unix_nano);
CREATE INDEX end_time_index
ON spans (end_time_unix_nano);
CREATE INDEX duration_index
ON spans (duration);