Telemetry Vendor Backends: Datadog & PostHog¶

// pkg/telemetry/datadog/datadog.go

package datadog

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "strings"
    "time"

    "github.com/cockroachdb/errors"
    gtbhttp "gitlab.com/phpboyscout/go-tool-base/pkg/http"
    "gitlab.com/phpboyscout/go-tool-base/pkg/logger"
    "gitlab.com/phpboyscout/go-tool-base/pkg/telemetry"
)

// Region identifies a Datadog data center region.
type Region string

const (
    RegionUS1 Region = "us1" // default
    RegionUS3 Region = "us3"
    RegionUS5 Region = "us5"
    RegionEU1 Region = "eu1"
    RegionAP1 Region = "ap1"
    RegionAP2 Region = "ap2"
    RegionGOV Region = "gov"
)

var regionEndpoints = map[Region]string{
    RegionUS1: "https://http-intake.logs.datadoghq.com/v1/input",
    RegionUS3: "https://http-intake.logs.us3.datadoghq.com/v1/input",
    RegionUS5: "https://http-intake.logs.us5.datadoghq.com/v1/input",
    RegionEU1: "https://http-intake.logs.datadoghq.eu/v1/input",
    RegionAP1: "https://http-intake.logs.ap1.datadoghq.com/v1/input",
    RegionAP2: "https://http-intake.logs.ap2.datadoghq.com/v1/input",
    RegionGOV: "https://http-intake.logs.ddog-gov.com/v1/input",
}

// Option configures the Datadog backend.
type Option func(*config)

type config struct {
    region Region
    source string
}

// WithRegion sets the Datadog region. Default: RegionUS1.
func WithRegion(region Region) Option {
    return func(c *config) { c.region = region }
}

// WithSource overrides the ddsource tag. Default: "gtb".
func WithSource(source string) Option {
    return func(c *config) { c.source = source }
}

type backend struct {
    endpoint string
    apiKey   string
    source   string
    client   *http.Client
    log      logger.Logger
}

// NewBackend creates a Datadog telemetry backend.
// apiKey is the Datadog API key (not an application key).
func NewBackend(apiKey string, log logger.Logger, opts ...Option) telemetry.Backend {
    cfg := &config{
        region: RegionUS1,
        source: "gtb",
    }
    for _, o := range opts {
        o(cfg)
    }

    endpoint, ok := regionEndpoints[cfg.region]
    if !ok {
        endpoint = regionEndpoints[RegionUS1]
    }

    return &backend{
        endpoint: endpoint,
        apiKey:   apiKey,
        source:   cfg.source,
        client:   gtbhttp.NewClient(gtbhttp.WithTimeout(5 * time.Second)),
        log:      log,
    }
}

// datadogEntry is the JSON structure for a single Datadog log entry.
type datadogEntry struct {
    Message   string            `json:"message"`
    DDSource  string            `json:"ddsource"`
    DDTags    string            `json:"ddtags"`
    Hostname  string            `json:"hostname"`
    Service   string            `json:"service"`
    Timestamp string            `json:"timestamp"`
    Level     string            `json:"level"`
    Metadata  map[string]string `json:"metadata,omitempty"`
}

func (b *backend) Send(ctx context.Context, events []telemetry.Event) error {
    entries := make([]datadogEntry, 0, len(events))

    for _, e := range events {
        tags := []string{
            fmt.Sprintf("event_type:%s", e.Type),
            fmt.Sprintf("tool_version:%s", e.Version),
            fmt.Sprintf("os:%s", e.OS),
            fmt.Sprintf("arch:%s", e.Arch),
        }

        entries = append(entries, datadogEntry{
            Message:   fmt.Sprintf("%s: %s", e.Type, e.Name),
            DDSource:  b.source,
            DDTags:    strings.Join(tags, ","),
            Hostname:  e.MachineID,
            Service:   e.ToolName,
            Timestamp: e.Timestamp.UTC().Format(time.RFC3339Nano),
            Level:     "info",
            Metadata:  e.Metadata,
        })
    }

    body, err := json.Marshal(entries)
    if err != nil {
        return errors.Wrap(err, "marshalling datadog entries")
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost, b.endpoint, bytes.NewReader(body))
    if err != nil {
        return errors.Wrap(err, "creating datadog request")
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("DD-API-KEY", b.apiKey)

    resp, err := b.client.Do(req)
    if err != nil {
        return nil // silently drop — telemetry must never block the user
    }
    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        b.log.Debug("datadog endpoint returned non-success status",
            "status", resp.StatusCode)
    }

    return nil
}

func (b *backend) Close() error { return nil }

import "gitlab.com/phpboyscout/go-tool-base/pkg/telemetry/datadog"

props.Tool{
    Name: "mytool",
    Features: props.SetFeatures(props.Enable(props.TelemetryCmd)),
    Telemetry: props.TelemetryConfig{
        Backend: func(p *props.Props) any {
            return datadog.NewBackend(
                os.Getenv("DD_API_KEY"),
                p.Logger,
                datadog.WithRegion(datadog.RegionEU1),
            )
        },
    },
}

// pkg/telemetry/posthog/posthog.go

package posthog

import (
    "bytes"
    "context"
    "encoding/json"
    "net/http"
    "time"

    "github.com/cockroachdb/errors"
    gtbhttp "gitlab.com/phpboyscout/go-tool-base/pkg/http"
    "gitlab.com/phpboyscout/go-tool-base/pkg/logger"
    "gitlab.com/phpboyscout/go-tool-base/pkg/telemetry"
)

// Instance identifies a PostHog deployment.
type Instance string

const (
    InstanceUS   Instance = "us"   // default
    InstanceEU   Instance = "eu"
)

var instanceEndpoints = map[Instance]string{
    InstanceUS: "https://us.i.posthog.com/capture/",
    InstanceEU: "https://eu.i.posthog.com/capture/",
}

// Option configures the PostHog backend.
type Option func(*config)

type config struct {
    instance Instance
    endpoint string // custom endpoint for self-hosted; overrides instance
}

// WithInstance sets the PostHog cloud instance. Default: InstanceUS.
func WithInstance(instance Instance) Option {
    return func(c *config) { c.instance = instance }
}

// WithEndpoint sets a custom endpoint for self-hosted PostHog.
// Takes precedence over WithInstance.
func WithEndpoint(endpoint string) Option {
    return func(c *config) { c.endpoint = endpoint }
}

type backend struct {
    endpoint   string
    projectKey string
    client     *http.Client
    log        logger.Logger
}

// NewBackend creates a PostHog telemetry backend.
// projectKey is the PostHog project API key (starts with "phc_").
func NewBackend(projectKey string, log logger.Logger, opts ...Option) telemetry.Backend {
    cfg := &config{
        instance: InstanceUS,
    }
    for _, o := range opts {
        o(cfg)
    }

    endpoint := cfg.endpoint
    if endpoint == "" {
        var ok bool
        endpoint, ok = instanceEndpoints[cfg.instance]
        if !ok {
            endpoint = instanceEndpoints[InstanceUS]
        }
    }

    return &backend{
        endpoint:   endpoint,
        projectKey: projectKey,
        client:     gtbhttp.NewClient(gtbhttp.WithTimeout(5 * time.Second)),
        log:        log,
    }
}

// posthogBatch is the top-level batch capture payload.
type posthogBatch struct {
    APIKey string         `json:"api_key"`
    Batch  []posthogEvent `json:"batch"`
}

// posthogEvent is a single PostHog event within a batch.
type posthogEvent struct {
    Event      string            `json:"event"`
    DistinctID string            `json:"distinct_id"`
    Timestamp  string            `json:"timestamp"`
    Properties map[string]string `json:"properties"`
}

func (b *backend) Send(ctx context.Context, events []telemetry.Event) error {
    batch := make([]posthogEvent, 0, len(events))

    for _, e := range events {
        props := map[string]string{
            "event_name":   e.Name,
            "tool_name":    e.ToolName,
            "tool_version": e.Version,
            "$os":          e.OS,
            "arch":         e.Arch,
        }

        // Merge custom metadata into properties
        for k, v := range e.Metadata {
            props[k] = v
        }

        batch = append(batch, posthogEvent{
            Event:      string(e.Type),
            DistinctID: e.MachineID,
            Timestamp:  e.Timestamp.UTC().Format(time.RFC3339Nano),
            Properties: props,
        })
    }

    payload := posthogBatch{
        APIKey: b.projectKey,
        Batch:  batch,
    }

    body, err := json.Marshal(payload)
    if err != nil {
        return errors.Wrap(err, "marshalling posthog batch")
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost, b.endpoint, bytes.NewReader(body))
    if err != nil {
        return errors.Wrap(err, "creating posthog request")
    }

    req.Header.Set("Content-Type", "application/json")

    resp, err := b.client.Do(req)
    if err != nil {
        return nil // silently drop — telemetry must never block the user
    }
    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        b.log.Debug("posthog endpoint returned non-success status",
            "status", resp.StatusCode)
    }

    return nil
}

func (b *backend) Close() error { return nil }

import "gitlab.com/phpboyscout/go-tool-base/pkg/telemetry/posthog"

props.Tool{
    Name: "mytool",
    Features: props.SetFeatures(props.Enable(props.TelemetryCmd)),
    Telemetry: props.TelemetryConfig{
        Backend: func(p *props.Props) any {
            return posthog.NewBackend(
                os.Getenv("POSTHOG_PROJECT_KEY"),
                p.Logger,
                posthog.WithInstance(posthog.InstanceEU),
            )
        },
    },
}

posthog.NewBackend(
    os.Getenv("POSTHOG_PROJECT_KEY"),
    p.Logger,
    posthog.WithEndpoint("https://posthog.internal.example.com/capture/"),
)

type ManifestTelemetry struct {
    Backend         string `yaml:"backend,omitempty"`          // "http", "otel", "datadog", "posthog"
    Endpoint        string `yaml:"endpoint,omitempty"`
    OTelEndpoint    string `yaml:"otel_endpoint,omitempty"`
    DatadogRegion   string `yaml:"datadog_region,omitempty"`
    PostHogInstance string `yaml:"posthog_instance,omitempty"`
    PostHogEndpoint string `yaml:"posthog_endpoint,omitempty"` // self-hosted override
}