Sign inSign up

chiefj/tracep-go

By chiefj

•Updated 3 months ago

Go tracer

Image
Developer tools
0

74

chiefj/tracep-go repository overview

⁠1. Quick Start (Ephemerial / Testing)

To spin up a temporary container exposing the service locally for testing (where data resets on container exit):

docker run --rm -d \
  -p 4318:4318 \
  -p 4319:4319 \
  --name tracep-test \
  chiefj/tracep-go:latest

⁠2. Production/Persistent Setup (Recommended)

Because the Go server uses a local SQLite database (traces.db), you must mount a persistent volume so trace data is not lost when the container is updated or restarted.

⁠Running with Docker CLI
# 1. Create a local directory for storage
mkdir -p $(pwd)/tracep-data

# 2. Start the container with persistence & configuration
docker run -d \
  -p 4318:4318 \
  -p 4319:4319 \
  -v $(pwd)/tracep-data:/app/data \
  -e TRACE_TOKEN="your-secure-auth-token" \
  -e RETENTION_HOURS=48 \
  --restart unless-stopped \
  --name tracep-server \
  chiefj/tracep-go:latest

⁠3. Configuration Variables

You can customize the container's behavior using the following environment variables (-e KEY=VALUE):

VariableDefaultDescription
TRACE_TOKENNoneSecure token required in the Authorization: Bearer <token> header. Keep blank to disable authentication.
RETENTION_HOURS48Auto-prune interval. Traces/spans older than this duration are automatically purged every 15 minutes.
DB_PATH/app/data/traces.dbThe internal filepath of the SQLite database.
INGEST_PORT4318Port that handles OpenTelemetry (OTLP) ingest.
QUERY_PORT4319Port that serves the Query/Dashboard APIs.
PORTNoneSet this to run in Single-Port Mode (multiplexes both Ingest and Query APIs on the same port, ideal for Render/Cloud Run).

⁠4. Troubleshooting & Verification

⁠Check Server Logs

To monitor the background cleanup task or incoming requests:

docker logs -f tracep-server
⁠API Testing Curl Commands

Below are the curls configured for a local persistent setup (change ports/host appropriately if running in single-port mode or on Render):

⁠1. Verify Health Status (Port 4319)
curl -i http://localhost:4319/health
⁠2. Ingest a Test Span (Port 4318)

Send a test span payload using the OTLP JSON format:

curl -i -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [
      {
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "4f6df6e5f689072a4f6df6e5f689072a",
                "spanId": "4f6df6e5f689072a",
                "name": "manual-debug-span",
                "startTimeUnixNano": "1687169400000000000",
                "endTimeUnixNano": "1687169400500000000"
              }
            ]
          }
        ]
      }
    ]
  }'
⁠3. Fetch Ingested Traces (Port 4319)
curl -i http://localhost:4319/traces
⁠4. Fetch Single Trace Details (Port 4319)
curl -i http://localhost:4319/traces/4f6df6e5f689072a4f6df6e5f689072a
⁠5. Fetch Single Span Details (Port 4319)
curl -i http://localhost:4319/spans/4f6df6e5f689072a
⁠6. List Namespaces/Classes (Port 4319)
curl -i http://localhost:4319/classes
⁠7. List Functions/Methods (Port 4319)
curl -i http://localhost:4319/functions

Tag summary

Content type

Image

Digest

sha256:064c2e199…

Size

9.3 MB

Last updated

3 months ago

docker pull chiefj/tracep-go