news.shamcode.ru | Как я создавал Observability для своих pet-проектов. Часть 2

В первой части мы развернули базовый стек для сбора метрик, логов и трейсов и интегрировали его с приложением на Laravel. Теперь покажу настройку Observability на примере простого Golang-приложения — настроим в нём структурированные логи, распределённый трейсинг и метрики, а также интегрируем с нашим стеком.

Для нетерпеливых, по традиции можете сразу посмотреть репозиторий с примером. Запускаете docker-compose up в корне и docker compose up в ./examaples/golang, переходите на http://localhost:3000 и пару раз обновляете страницу http://localhost:8080/hello что бы сгенерировать нагрузку.

Создаем простой сервис

Начнём с создания минимального HTTP-сервиса на Go, который будем использовать для тестирования логирования и трассировки. Напишем небольшое веб-приложение: оно будет слушать HTTP-порт и обрабатывать один-два маршрута. Например,
сделаем эндпоинт /hello, возвращающий простое сообщение. Создадим файл main.go со следующим содержанием:

package main

import (
	"fmt"
	"log"
	"net/http"
)

func helloHandler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "Hello, Observability!")
}

func main() {
	http.HandleFunc("/hello", helloHandler)
	log.Println("Starting server on :8080...")
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		log.Fatalf("Server failed: %s", err)
	}
}

Этот код запускает HTTP-сервер на порту 8080 и регистрирует обработчик helloHandler на путь /hello. Функция просто пишет текстовый ответ клиенту. Логи мы пока выводим через стандартный log.Println – этого достаточно, чтобы убедиться, что
сервис работает. Запустив приложение, можно проверить в браузере или с помощью curl http://localhost:8080/hello, что оно возвращает “Hello, Observability!”. Теперь усложним его, добавляя необходимые для Observability инструменты.

Структурированные логи

Вместо использования стандартного логера, перейдем на slog – библиотеку для структурированного логирования, появившуюся в поставке Go 1.21. Она позволяет удобно добавлять к сообщениям поля (ключ-значение) и лучше подходит для последующей отправки логов в системы мониторинга. Чтобы интегрировать slog с нашим Observability-стеком, воспользуемся OpenTelemetry для slog (otelslog). Он перехватывает сообщения slog и обогащает их данными о трассировке (например, trace_id), позволяя коррелировать логи с запросами. Кроме того, через otelslog мы будем отправлять логи напрямую в OpenTelemetry Collector по протоколу OTLP, минуя Vector.

Сначала добавим нужные зависимости OpenTelemetry в проект:

go get go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc \
      go.opentelemetry.io/otel/sdk/log \
      go.opentelemetry.io/otel/log/global \
      go.opentelemetry.io/contrib/bridges/otelslog

Затем настроим провайдер логов в коде. Для простоты сразу укажем адрес OTEL Collector и отключим TLS (так как Collector слушает без шифрования внутри Docker-сети):

package main

import (
	"go.opentelemetry.io/contrib/bridges/otelslog"
	"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc"
	"go.opentelemetry.io/otel/log/global"
	"go.opentelemetry.io/otel/sdk/log"
)

func initLogger(ctx context.Context) func() {
	logExporter, err := otlploggrpc.New(ctx, otlploggrpc.WithEndpoint("otel-collector:4317"), otlploggrpc.WithInsecure())
	if err != nil {
		panic(fmt.Sprintf("failed to initialize OTLP log exporter: %v", err))
	}

	res, err := resource.New(ctx,
		resource.WithAttributes(semconv.ServiceNameKey.String("go-app")),
	)
	if err != nil {
		panic(fmt.Sprintf("resource creation error: %v", err))
	}

	lp := log.NewLoggerProvider(
		log.WithResource(res),
		log.WithProcessor(log.NewBatchProcessor(logExporter)),
	)

	global.SetLoggerProvider(lp)

	slog.SetDefault(otelslog.NewLogger("go-app"))

	return func() {
		if err := lp.Shutdown(ctx); err != nil {
			panic(fmt.Sprintf("failed to shutdown logger provider: %v", err))
		}
	}
}

С помощью этой функции мы настраиваем экспорт структурированных логов в OpenTelemetry Collector по протоколу OTLP. После этого создаём LoggerProvider с батч-обработчиком и регистрируем его глобально. Последняя строка заменяет логгер по
умолчанию на otelslog.NewLogger("go-app") – это автоматически добавит в каждый лог поле service name и данные трассировки (trace_id/span_id). В конце функции возвращаем lp.Shutdown, чтобы корректно завершить работу приложения.

Теперь используем новый логгер в наших обработчиках. Например, расширим функцию helloHandler, чтобы она записывала структурированный лог при каждом запросе:

package main

func helloHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
	slog.InfoContext(ctx, "Handling /hello request",
		"method", r.Method,
		"user_agent", r.UserAgent())
	_, err := fmt.Fprintln(w, "Hello, Observability!")
	if err != nil {
		slog.Error("Failed to write response", "error", err)
		return
	}
}

Здесь мы вызываем slog.InfoContext, передавая контекст запроса и несколько полей: метод HTTP-запроса и User-Agent клиента. Можем запустить наше приложение и перейти по адресу http://localhost:8080/hello, чтобы увидеть, что логи теперь
структурированы и содержат дополнительные данные.

Но как вы можете заметить, логи не содержат информации о trace_id и отправка их в OpenTelemetry Collector не происходит. Мы пока не собрали нужный контейнер который будет связан с нашим приложением, а так же не настроили трейсинг. Давайте
перейдем к этому.

Распределённый трейсинг

Подключим OpenTelemetry для сбора трейсов нашего Go-сервиса. С помощью OpenTelemetry Go SDK мы создадим TracerProvider и настроим экспорт трейсов в OTEL Collector, откуда они попадут в Jaeger и Tempo. Также инструментируем HTTP-сервер, чтобы каждый входящий запрос порождал span (трейс) с необходимыми атрибутами.

Добавим зависимости для трейсинга:

go get go.opentelemetry.io/otel/sdk/trace \
      go.opentelemetry.io/otel/trace \
      go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc \
      go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp \
      go.opentelemetry.io/otel/sdk/resource \
      go.opentelemetry.io/otel/semconv/v1.30.0

Настроим глобальный TracerProvider в коде, аналогично тому, как делали для логов:

package main

import (
	"context"
	"os"

	"go.opentelemetry.io/contrib/bridges/otelslog"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	"go.opentelemetry.io/otel/log/global"
	"go.opentelemetry.io/otel/sdk/log"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
)

func initTracer(ctx context.Context) func() {
	exp, err := otlptracegrpc.New(ctx,
		otlptracegrpc.WithEndpoint("otel-collector:4317"),
		otlptracegrpc.WithInsecure())
	if err != nil {
		panic("failed to create trace exporter: " + err.Error())
	}

	res, err := resource.New(ctx,
		resource.WithAttributes(semconv.ServiceNameKey.String("go-app")))
	if err != nil {
		panic(fmt.Sprintf("resource creation error: %v", err))
	}

	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exp,
			sdktrace.WithMaxExportBatchSize(512),
			sdktrace.WithBatchTimeout(5*time.Second)),
		sdktrace.WithResource(res),
	)

	otel.SetTracerProvider(tp)

	return func() {
		_ = tp.Shutdown(context.Background())
	}
}

В этой функции аналогично создается OTLP экспортер, и TracerProvider с ресурсом. Это имя сервиса потом позволит фильтровать трейсы в Jaeger/Tempo. Функция возвращает tp.Shutdown, которая позволяет корректно завершить работу при выходе из
приложения.

Далее, инструментируем HTTP-сервер. Пакет otelhttp из opentelemetry-go-contrib - это middleware для стандартного net/http, который автоматически создаёт span для каждого входящего запроса. Им воспользуемся при настройке маршрутов. Вместо прямого вызова http.HandleFunc, обернём наш обработчик:

mux := http.NewServeMux()  
mux.Handle("/hello", otelhttp.NewHandler(http.HandlerFunc(helloHandler), "/hello"))

Благодаря otelhttp.NewHandler, при каждом запросе к /hello будет создаваться новый span с именем "/hello" (можно указывать другое имя операции вторым параметром). В контексте, который получит helloHandler, уже будет установлен активный span – поэтому, вызывая slog.InfoContext(ctx, ...), мы автоматически привяжем лог к ID этого спана. При желании, мы можем добавить вложенные спаны внутри обработчиков для более детализированной трассировки. Например, можно искусственно создать дополнительный span вокруг какой-то логики:

package main

func helloHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
	// Создаём новый span вокруг обработки запроса
	_, span := otel.Tracer("go-app").Start(ctx, "businessLogic")
	defer span.End()

	// ... Бизнес логика ...

	// Логируем результат
	slog.InfoContext(ctx, "Handled /hello request", "method", r.Method)
	fmt.Fprintln(w, "Hello, Observability!")
}

Здесь мы получаем глобальный трейсер и начинаем новый спан "businessLogic". В реальном приложении, думаю понятно что может быть размещено вместо комментария. Для примера мы просто сразу завершаем спан. Лог по-прежнему пишется с ctx
запроса (обратите внимание, мы используем исходный ctx, а не тот, что вернул Tracer.Start, чтобы привязка лога осталась к родительскому span). В итоге в Jaeger/Tempo мы увидим, что внутри основного HTTP-запроса есть вложенный шаг
"businessLogic". Остаётся инициализировать всё при старте сервера. В функции main перед ListenAndServe добавим вызовы наших инициализаторов:

package main

func main() {
	ctx := context.Background()
	shutdownTracer := initTracer(ctx)
	defer shutdownTracer()

	shutdownLogger := initLogger(ctx)
	defer shutdownLogger()

	mux := http.NewServeMux()
	mux.Handle("/hello", otelhttp.NewHandler(http.HandlerFunc(helloHandler), "/hello"))

	srv := &http.Server{Addr: ":8080", Handler: mux}
	fmt.Printf("Starting server on :8080...")
	if err := srv.ListenAndServe(); err != nil {
		slog.Error("Failed to start server", "error", err)
		os.Exit(1)
	}
}

Теперь наше приложение будет отправлять трейсы и логи которые содержат trace_is в OpenTelemetry Collector, а оттуда они попадут в Jaeger, Tempo и Loki.

Важно отметить, что поддержка логов в OpenTelemetry Go пока экспериментальная. Если нужно стабильности, то можно легко по аналогии собирать логи через Vector. А теперь займемся метриками.

Метрики

Для сбора метрик мы воспользуемся стандартной библиотекой client_golang от Prometheus. Она позволит нам публиковать метрики в формате, который затем соберёт VictoriaMetrics. В отличие от трейсов и логов, метрики мы не будем отправлять через OTEL Collector, а просто организуем эндпоинт /metrics и настроим сбор метрик.

Добавим клиент Prometheus в зависимости:

go get github.com/prometheus/client_golang/prometheus \
github.com/prometheus/client_golang/prometheus/promhttp

Определим несколько метрик. Для примера введём счетчик HTTP-запросов и гистограмму для времени ответа. Их можно определить как глобальные переменные и регистрировать при инициализации:

package main

import "github.com/prometheus/client_golang/prometheus"

var (
	requestCount = prometheus.NewCounter(prometheus.CounterOpts{
		Name: "goapp_http_requests_total",
		Help: "Total number of HTTP requests handled by the Go app",
	})
	responseDuration = prometheus.NewHistogram(prometheus.HistogramOpts{
		Name:    "goapp_response_duration_seconds",
		Help:    "Histogram of response durations for /hello",
		Buckets: prometheus.DefBuckets,
	})
)

func init() {
	// Регистрируем метрики в глобальном реестре Prometheus
	prometheus.MustRegister(requestCount, responseDuration)
}

Здесь goapp_http_requests_total — счётчик запросов, а goapp_response_duration_seconds — гистограмма длительности обработки. Мы используем дефолтные "бакеты" для гистограммы (стандартные интервалы). В init() регистрируем их, чтобы клиентская библиотека знала о них.

Теперь в обработчике обновляем эти метрики:

package main

func helloHandler(w http.ResponseWriter, r *http.Request) {
	timer := prometheus.NewTimer(responseDuration) // начинаем таймер для гистограммы
	defer timer.ObserveDuration()                  // зафиксируем время по завершении

	// ... (логика, логирование и т.д., как выше) ...

	requestCount.Inc() // увеличиваем счетчик запросов
	_, err := fmt.Fprintln(w, "Hello, Observability!")
	if err != nil {
		slog.Error("Failed to write response", "error", err)
		return
	}
}

Мы обернули выполнение запроса с помощью NewTimer — он автоматически измерит время выполнения обработчика и запишет в гистограмму responseDuration при выходе. Также каждый запрос инкрементирует счётчик requestCount.

Остается только опубликовать метрики на отдельном эндпоинте. Для этого добавим обработчик /metrics:

package main

import "github.com/prometheus/client_golang/prometheus/promhttp"

// ... внутри main() после настройки mux:
mux.Handle("/metrics", promhttp.Handler())

Теперь вы можете запустить приложение и перейти на http://localhost:8080/metrics, чтобы увидеть, что метрики успешно собираются. Так же вы можете видеть метрики, которые идут вместе с библиотекой. Всё, что осталось, — настроить сбор
метрик в VictoriaMetrics.

На стороне VictoriaMetrics нужно добавить новую цель для сбора. В файле victoriametrics-scrape.yml, который мы настроили в первой части, пропишем новый job для Go-сервиса, аналогично тому, как делали для Laravel:

- job_name: 'go_app'
  scrape_interval: 15s
  static_configs:
    - targets: [ 'go-app:8080' ]

Здесь предполагается, что контейнер с нашим Go-приложением имеет имя go-app. VictoriaMetrics будет опрашивать эндпоинт go-app:8080/metrics каждые 15 секунд и сохранять метрики. (Если у вас другой порт или имя сервиса, не забудьте их указать.)

После обновления конфигурации, перезапустим сервис VictoriaMetrics, чтобы новый job вступил в силу.

docker compose restart victoriametrics

Контейнер

Наше приложение готово, и метрики/логи/трейсы настроены на отправку. Теперь интегрируем его в существующую инфраструктуру. Потребуется добавить новый сервис в docker-compose.yaml и подключить его к сети мониторинга. Ну и подготовить Dockerfile для сборки образа. Начнем с последнего:

FROM golang:1.24-alpine AS builder

WORKDIR /build

COPY ./go.mod ./go.sum ./
RUN go mod download

COPY . .

RUN CGO_ENABLED=0 go build -ldflags="-w -s" -o go-app main.go

FROM alpine:latest

RUN apk --no-cache add ca-certificates && \
    addgroup -S appgroup && adduser -S appuser -G appgroup

COPY --from=builder /build/go-app /app/go-app

USER appuser

WORKDIR /app

EXPOSE 8080

ENTRYPOINT ["/app/go-app", "sync", "-d"]

Теперь добавим сервис docker-compose:

services:
  go-app:
    build: .
    container_name: go-app
    ports:
      - "8080:8080"
    networks:
      - monitoring

networks:
  monitoring:
    external: true

Обратите внимание на подключение к сети monitoring – благодаря этому наше приложение сможет достучаться до otel-collector, victoriametrics и других компонентов по именам и сервис будет доступен для них.

Теперь можем запустить наше приложение:

docker compose up -d --build go-app

После запуска, перейдите на http://localhost:8080/hello, чтобы убедиться, что приложение работает и стоит пару раз обновить страницу, что бы сгенерировать простую нагрузку.
После чего переходим в grafana (сервис которы который мы описали в прошлой статье думаю уже запущен, если не запущен - запустите). Перейдите в раздел Metrics и введите запрос goapp_http_requests_total - вы увидите график с количеством запросов к нашему сервису.

Теперь перейдите в раздел Explore, выберите Jaeger или Tempo в выпадающем списке и выберете сервис go-app - вы увидите трейсы запросов к нашему сервису.

Ну и теперь можно зайти в раздел Logs и посмотреть логи нашего сервиса.

Если остались вопросы или хотите обсудить тему подробнее — пишите в комментариях и подписывайтесь на мой канал в Telegram.