snowplow

ExampleEmitter_Collector demonstrates how to access and use the metrics collector from an emitter for Prometheus monitoring.

package main

import (
	"log"

	"github.com/prometheus/client_golang/prometheus"
	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	// Create an emitter as usual
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	// Access the Prometheus collector for metrics export
	collector := emitter.Collector()

	// The collector can be registered with a Prometheus registry.
	// Registry can be next exposed with HTTP for Prometheus to
	// scrape the metrics.
	registry := prometheus.NewRegistry()
	registry.MustRegister(collector)

	// Use the emitter normally; metrics are collected automatically
	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	err = tracker.TrackEvent("page_view", map[string]any{"page": "/home"})
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	tracker.Stop()
}

Output:

ExampleTracker_Stop demonstrates proper shutdown.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track some events
	err = tracker.TrackEvent("event1", nil)
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	err = tracker.TrackEvent("event2", nil)
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	// Stop waits for in-progress sends to complete before shutdown.
	tracker.Stop()
}

Output:

ExampleTracker_TrackBillingEvent demonstrates tracking a billing event.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track a billing event with minimal required fields.
	// The event is sent as a Snowplow structured event with billing context attached.
	// Realm must be one of: "SaaS", "Dedicated", "SM"
	err = tracker.TrackBillingEvent(
		snowplow.BillingEventRequiredInput{
			Category:      "CodeSuggestionsService",
			EventType:     "code_completions",
			Realm:         "SaaS",
			UnitOfMeasure: "tokens",
			Quantity:      150.0,
		},
	)
	if err != nil {
		log.Printf("Failed to track billing event: %v", err)
	}

	tracker.Stop()
}

Output:

ExampleTracker_TrackBillingEventWithOptionalInput demonstrates tracking a billing event with context options.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track a billing event with full context for billing reconciliation.
	// All optional fields help identify the source and context of the billable usage.
	err = tracker.TrackBillingEventWithOptionalInput(
		snowplow.BillingEventRequiredInput{
			Category:      "CodeSuggestionsService",
			EventType:     "code_generations",
			Realm:         "SaaS",
			UnitOfMeasure: "tokens",
			Quantity:      500.0,
		},
		snowplow.BillingEventOptionalInput{
			InstanceID:      "instance-abc123",
			ProjectID:       12345,
			NamespaceID:     67890,
			OrganizationID:  22222,
			RootNamespaceID: 11111,
			Subject:         "user-456",
			GlobalUserID:    "global-user-789",
			CorrelationID:   "request-correlation-xyz",
			DeploymentType:  "self-managed",
			EntityID:        "entity-abc",
			Metadata: map[string]any{
				"model":    "claude-3",
				"language": "go",
			},
		},
	)
	if err != nil {
		log.Printf("Failed to track billing event: %v", err)
	}

	tracker.Stop()
}

Output:

ExampleTracker_TrackEvent demonstrates tracking a simple event without properties.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track a simple event with just a name (no properties).
	// Pass nil for events without additional properties.
	err = tracker.TrackEvent("user_login", nil)
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	tracker.Stop()
}

Output:

ExampleTracker_TrackEvent_withNestedProperties demonstrates tracking events with nested properties.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track an event with nested properties (multi-level structure).
	// Supports nested maps and complex data structures.
	err = tracker.TrackEvent("page_view", map[string]any{
		"title":    "Product Details - Premium Widget",
		"duration": 4500,
		"user": map[string]any{
			"id":       67890,
			"username": "john_doe",
		},
	})
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	tracker.Stop()
}

Output:

ExampleTracker_TrackEvent_withProperties demonstrates tracking events with simple properties.

package main

import (
	"log"

	"gitlab.com/gitlab-org/labkit/v2/events/snowplow"
)

func main() {
	emitter, err := snowplow.NewEmitter("http://localhost:9093/com.snowplowanalytics.snowplow/tp2")
	if err != nil {
		log.Fatalf("Failed to create emitter: %v", err)
	}

	tracker, err := snowplow.NewTracker("my-application", emitter)
	if err != nil {
		log.Fatalf("Failed to create tracker: %v", err)
	}

	// Track an event with simple properties (flat structure).
	// Supports string, int, float, bool types.
	err = tracker.TrackEvent("button_clicked", map[string]any{
		"button_id": "submit_form",
		"user_id":   12345,
	})
	if err != nil {
		log.Printf("Failed to track event: %v", err)
	}

	tracker.Stop()
}

Output: