feat: add grafana-lgtm module (#2660)

* feat: init grafana module

* chore: refactor layout

* chore: add connection methods to the container

* chore: a comprenhensive example using Otel libraries

* feat<: add option for credentials

* fix: lint

* docs: mark version for the grafana methods

* fix: mod tidy

* fix: lint

* fix: lint

* fix: include schema

.github/workflows/ci.yml

@@ -94,7 +94,7 @@ jobs:
       matrix:
         go-version: [1.21.x, 1.x]
         platform: [ubuntu-latest]
-        module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, dolt, elasticsearch, gcloud, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, valkey, vault, vearch, weaviate]
+        module: [artemis, azurite, cassandra, chroma, clickhouse, cockroachdb, compose, consul, couchbase, dolt, elasticsearch, gcloud, grafana-lgtm, inbucket, influxdb, k3s, k6, kafka, localstack, mariadb, milvus, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, ollama, openfga, openldap, opensearch, postgres, pulsar, qdrant, rabbitmq, redis, redpanda, registry, surrealdb, valkey, vault, vearch, weaviate]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: ${{ matrix.go-version }}

.vscode/.testcontainers-go.code-workspace

@@ -61,6 +61,10 @@
             "name": "module / gcloud",
             "path": "../modules/gcloud"
         },
+        {
+            "name": "module / grafana-lgtm",
+            "path": "../modules/grafana-lgtm"
+        },
         {
             "name": "module / inbucket",
             "path": "../modules/inbucket"

docs/modules/grafana-lgtm.md

@@ -0,0 +1,115 @@
+# Grafana LGTM
+
+Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## Introduction
+
+The Testcontainers module for Grafana LGTM.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Grafana module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/grafanalgtm
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:runGrafanaLGTMContainer
+<!--/codeinclude-->
+
+## Module Reference
+
+### Run function
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+!!!info
+    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.
+
+The Grafana LGTM module exposes one entrypoint function to create the Grafana LGTM container, and this function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*GrafanaLGTMContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Grafana LGTM container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different Grafana LGTM Docker image, you can set a valid Docker image as the second argument in the `Run` function.
+E.g. `Run(context.Background(), "grafana/otel-lgtm:0.6.0")`.
+
+#### Admin Credentials
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+If you need to set different admin credentials in the Grafana LGTM container, you can set them using the `WithAdminCredentials(user, password)` option.
+
+{% include "../features/common_functional_options.md" %}
+
+### Container Methods
+
+The Grafana LGTM container exposes the following methods:
+
+!!!info
+    All the endpoint methods return their endpoints in the format `<host>:<port>`, so please use them accordingly to configure your client.
+
+#### Grafana Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `HttpEndpoint(ctx)` method returns the HTTP endpoint to connect to Grafana, using the default `3000` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Loki Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `LokiEndpoint(ctx)` method returns the HTTP endpoint to connect to Loki, using the default `3100` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Tempo Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `TempoEndpoint(ctx)` method returns the HTTP endpoint to connect to Tempo, using the default `3200` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Otel HTTP Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `OtelHTTPEndpoint(ctx)` method returns the endpoint to connect to Otel using HTTP, using the default `4318` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Otel gRPC Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `OtelGRPCEndpoint(ctx)` method returns the endpoint to connect to Otel using gRPC, using the default `4317` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+#### Prometheus Endpoint
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `PrometheusHttpEndpoint(ctx)` method returns the endpoint to connect to Prometheus, using the default `9090` port. The same method with the `Must` prefix returns just the endpoing, and panics if an error occurs.
+
+## Examples
+
+### Traces, Logs and Prometheus metrics for a simple Go process
+
+In this example, a simple application is created to generate traces, logs, and Prometheus metrics.
+The application sends data to Grafana LGTM, and the Otel SDK is used to send the data.
+The example demonstrates how to set up the Otel SDK and run the Grafana LGTM module,
+configuring the Otel library to send data to Grafana LGTM thanks to the endpoints provided by the Grafana LGTM container.
+
+<!--codeinclude-->
+[App sending Otel data](../../modules/grafana-lgtm/examples_test.go) inside_block:rollDiceApp
+[Setup Otel SDK](../../modules/grafana-lgtm/examples_test.go) inside_block:setupOTelSDK
+[Run the Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:ExampleRun_otelCollector
+<!--/codeinclude-->

mkdocs.yml

@@ -76,6 +76,7 @@ nav:
         - modules/dolt.md
         - modules/elasticsearch.md
         - modules/gcloud.md
+        - modules/grafana-lgtm.md
         - modules/inbucket.md
         - modules/influxdb.md
         - modules/k3s.md

modules/grafana-lgtm/Makefile

@@ -0,0 +1,5 @@
+include ../../commons-test.mk
+
+.PHONY: test
+test:
+	$(MAKE) test-grafanalgtm

modules/grafana-lgtm/examples_test.go

@@ -0,0 +1,233 @@
+package grafanalgtm_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	golog "log"
+	"log/slog"
+	"math/rand"
+	"sync"
+	"time"
+
+	"go.opentelemetry.io/contrib/bridges/otelslog"
+	"go.opentelemetry.io/contrib/instrumentation/runtime"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
+	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/exporters/prometheus"
+	"go.opentelemetry.io/otel/log/global"
+	metricsapi "go.opentelemetry.io/otel/metric"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/log"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/trace"
+
+	"github.com/testcontainers/testcontainers-go/modules/grafanalgtm"
+)
+
+func ExampleRun() {
+	// runGrafanaLGTMContainer {
+	ctx := context.Background()
+
+	grafanaLgtmContainer, err := grafanalgtm.Run(ctx, "grafana/otel-lgtm:0.6.0")
+	if err != nil {
+		golog.Fatalf("failed to start container: %s", err)
+	}
+
+	// Clean up the container
+	defer func() {
+		if err := grafanaLgtmContainer.Terminate(ctx); err != nil {
+			golog.Fatalf("failed to terminate container: %s", err) // nolint:gocritic
+		}
+	}()
+	// }
+
+	state, err := grafanaLgtmContainer.State(ctx)
+	if err != nil {
+		golog.Fatalf("failed to get container state: %s", err) // nolint:gocritic
+	}
+
+	fmt.Println(state.Running)
+
+	// Output:
+	// true
+}
+
+func ExampleRun_otelCollector() {
+	ctx := context.Background()
+
+	ctr, err := grafanalgtm.Run(ctx, "grafana/otel-lgtm:0.6.0", grafanalgtm.WithAdminCredentials("admin", "123456789"))
+	if err != nil {
+		golog.Fatalf("failed to start Grafana LGTM container: %s", err)
+	}
+	defer func() {
+		if err := ctr.Terminate(ctx); err != nil {
+			golog.Fatalf("failed to terminate Grafana LGTM container: %s", err)
+		}
+	}()
+
+	// Set up OpenTelemetry.
+	otelShutdown, err := setupOTelSDK(ctx, ctr)
+	if err != nil {
+		return
+	}
+	// Handle shutdown properly so nothing leaks.
+	defer func() {
+		err = errors.Join(err, otelShutdown(context.Background()))
+	}()
+
+	// roll dice 10000 times, concurrently
+	max := 10_000
+	wg := sync.WaitGroup{}
+	for i := 0; i < max; i++ {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+			rolldice(ctx)
+		}()
+	}
+
+	wg.Wait()
+
+	// Output:
+	// shutdown errors: <nil>
+}
+
+// setupOTelSDK bootstraps the OpenTelemetry pipeline.
+// If it does not return an error, make sure to call shutdown for proper cleanup.
+func setupOTelSDK(ctx context.Context, ctr *grafanalgtm.GrafanaLGTMContainer) (shutdown func(context.Context) error, err error) { // nolint:nonamedreturns // this is a pattern in the OpenTelemetry Go SDK
+	var shutdownFuncs []func(context.Context) error
+
+	// shutdown calls cleanup functions registered via shutdownFuncs.
+	// The errors from the calls are joined.
+	// Each registered cleanup will be invoked once.
+	shutdown = func(ctx context.Context) error {
+		var err error
+		for _, fn := range shutdownFuncs {
+			err = errors.Join(err, fn(ctx))
+		}
+		shutdownFuncs = nil
+		fmt.Println("shutdown errors:", err)
+		return err
+	}
+
+	// handleErr calls shutdown for cleanup and makes sure that all errors are returned.
+	handleErr := func(inErr error) {
+		err = errors.Join(inErr, shutdown(ctx))
+	}
+
+	prop := propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		propagation.Baggage{},
+	)
+	otel.SetTextMapPropagator(prop)
+
+	otlpHttpEndpoint := ctr.MustOtlpHttpEndpoint(ctx)
+
+	traceExporter, err := otlptrace.New(ctx,
+		otlptracehttp.NewClient(
+			// adding schema to avoid this error:
+			// 2024/07/19 13:16:30 internal_logging.go:50: "msg"="otlptrace: parse endpoint url" "error"="parse \"127.0.0.1:33007\": first path segment in URL cannot contain colon" "url"="127.0.0.1:33007"
+			// it does not happen with the logs and metrics exporters
+			otlptracehttp.WithEndpointURL("http://"+otlpHttpEndpoint),
+			otlptracehttp.WithInsecure(),
+		),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	tracerProvider := trace.NewTracerProvider(trace.WithBatcher(traceExporter))
+	if err != nil {
+		handleErr(err)
+		return
+	}
+	shutdownFuncs = append(shutdownFuncs, tracerProvider.Shutdown)
+	otel.SetTracerProvider(tracerProvider)
+
+	metricExporter, err := otlpmetrichttp.New(ctx,
+		otlpmetrichttp.WithInsecure(),
+		otlpmetrichttp.WithEndpoint(otlpHttpEndpoint),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	// The exporter embeds a default OpenTelemetry Reader and
+	// implements prometheus.Collector, allowing it to be used as
+	// both a Reader and Collector.
+	prometheusExporter, err := prometheus.New()
+	if err != nil {
+		return nil, err
+	}
+
+	meterProvider := metric.NewMeterProvider(
+		metric.WithReader(metric.NewPeriodicReader(metricExporter)),
+		metric.WithReader(prometheusExporter),
+	)
+	if err != nil {
+		handleErr(err)
+		return
+	}
+	shutdownFuncs = append(shutdownFuncs, meterProvider.Shutdown)
+	otel.SetMeterProvider(meterProvider)
+
+	logExporter, err := otlploghttp.New(ctx,
+		otlploghttp.WithInsecure(),
+		otlploghttp.WithEndpoint(otlpHttpEndpoint),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	loggerProvider := log.NewLoggerProvider(log.WithProcessor(log.NewBatchProcessor(logExporter)))
+	if err != nil {
+		handleErr(err)
+		return
+	}
+	shutdownFuncs = append(shutdownFuncs, loggerProvider.Shutdown)
+	global.SetLoggerProvider(loggerProvider)
+
+	err = runtime.Start(runtime.WithMinimumReadMemStatsInterval(time.Second))
+	if err != nil {
+		logger.ErrorContext(ctx, "otel runtime instrumentation failed:", err) // nolint:all // this is a pattern in the OpenTelemetry Go SDK
+	}
+
+	return
+}
+
+// rollDiceApp {
+const schemaName = "https://github.com/grafana/docker-otel-lgtm"
+
+var (
+	tracer = otel.Tracer(schemaName)
+	logger = otelslog.NewLogger(schemaName)
+	meter  = otel.Meter(schemaName)
+)
+
+func rolldice(ctx context.Context) {
+	ctx, span := tracer.Start(ctx, "roll")
+	defer span.End()
+
+	// 20-sided dice
+	roll := 1 + rand.Intn(20)
+	logger.InfoContext(ctx, fmt.Sprintf("Rolled a dice: %d\n", roll), slog.Int("result", roll))
+
+	opt := metricsapi.WithAttributes(
+		attribute.Key("sides").Int(roll),
+	)
+
+	// This is the equivalent of prometheus.NewCounterVec
+	counter, err := meter.Int64Counter("rolldice-counter", metricsapi.WithDescription("a 20-sided dice"))
+	if err != nil {
+		golog.Fatal(err)
+	}
+	counter.Add(ctx, int64(roll), opt)
+}
+
+// }