> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Golang SDK для ClickStack — стека обсервабилити ClickHouse

# Golang

ClickStack использует стандарт OpenTelemetry для сбора телеметрических данных (журналов и
трейсов). Трейсы автоматически создаются с помощью автоматического
инструментирования, поэтому для получения пользы от трассировки ручное
инструментирование не требуется.

**В этом руководстве рассматриваются:**

<table>
  <tbody>
    <tr>
      <td className="pe-2">✅ Журналы</td>
      <td className="pe-2">✅ Метрики</td>
      <td className="pe-2">✅ Трейсы</td>
    </tr>
  </tbody>
</table>

<div id="getting-started">
  ## Начало работы
</div>

<div id="install-opentelemetry">
  ### Установите пакеты инструментирования OpenTelemetry
</div>

Чтобы установить Go-пакеты OpenTelemetry и HyperDX, используйте приведённую ниже команду. Рекомендуется ознакомиться с [актуальными пакетами инструментирования](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/v1.4.0/instrumentation#instrumentation-packages) и установить необходимые пакеты, чтобы данные трассировки корректно добавлялись.

```shell theme={null}
go get -u go.opentelemetry.io/otel
go get -u github.com/hyperdxio/otel-config-go
go get -u github.com/hyperdxio/opentelemetry-go
go get -u github.com/hyperdxio/opentelemetry-logs-go
```

<div id="native-http-server-example">
  ### Пример нативного HTTP-сервера (net/http)
</div>

В этом примере мы будем использовать `net/http/otelhttp`.

```shell theme={null}
go get -u go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
```

Обратитесь к разделам с комментариями, чтобы узнать, как добавить в Go-приложение сбор телеметрии.

```go theme={null}

package main

import (
  "context"
  "io"
  "log"
  "net/http"
  "os"

  "github.com/hyperdxio/opentelemetry-go/otelzap"
  "github.com/hyperdxio/opentelemetry-logs-go/exporters/otlp/otlplogs"
  "github.com/hyperdxio/otel-config-go/otelconfig"
  "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
  "go.opentelemetry.io/otel/trace"
  "go.uber.org/zap"
  sdk "github.com/hyperdxio/opentelemetry-logs-go/sdk/logs"
  semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
  "go.opentelemetry.io/otel/sdk/resource"
)

// настройка общих атрибутов для всех журналов
func newResource() *resource.Resource {
  hostName, _ := os.Hostname()
  return resource.NewWithAttributes(
    semconv.SchemaURL,
    semconv.ServiceVersion("1.0.0"),
    semconv.HostName(hostName),
  )
}

// прикрепление trace id к журналу
func WithTraceMetadata(ctx context.Context, logger *zap.Logger) *zap.Logger {
  spanContext := trace.SpanContextFromContext(ctx)
  if !spanContext.IsValid() {
    // ctx не содержит допустимого span.
    // Нет trace metadata для добавления.
    return logger
  }
  return logger.With(
    zap.String("trace_id", spanContext.TraceID().String()),
    zap.String("span_id", spanContext.SpanID().String()),
  )
}

func main() {
  // Инициализация конфигурации OTel и её использование во всём приложении
  otelShutdown, err := otelconfig.ConfigureOpenTelemetry()
  if err != nil {
    log.Fatalf("error setting up OTel SDK - %e", err)
  }
  defer otelShutdown()

  ctx := context.Background()

  // настройка провайдера логирования OpenTelemetry
  logExporter, _ := otlplogs.NewExporter(ctx)
  loggerProvider := sdk.NewLoggerProvider(
    sdk.WithBatcher(logExporter),
  )
  // корректное завершение работы логгера для сброса накопленных сигналов перед завершением программы
  defer loggerProvider.Shutdown(ctx)

  // создание нового логгера с ядром OpenTelemetry zap и установка его глобально
  logger := zap.New(otelzap.NewOtelCore(loggerProvider))
  zap.ReplaceGlobals(logger)
  logger.Warn("hello world", zap.String("foo", "bar"))

  http.Handle("/", otelhttp.NewHandler(wrapHandler(logger, ExampleHandler), "example-service"))

  port := os.Getenv("PORT")
  if port == "" {
    port = "7777"
  }

  logger.Info("** Service Started on Port " + port + " **")
  if err := http.ListenAndServe(":"+port, nil); err != nil {
    logger.Fatal(err.Error())
  }
}

// Используйте это для оборачивания всех обработчиков, чтобы добавить trace metadata к логгеру
func wrapHandler(logger *zap.Logger, handler http.HandlerFunc) http.HandlerFunc {
  return func(w http.ResponseWriter, r *http.Request) {
    logger := WithTraceMetadata(r.Context(), logger)
    logger.Info("request received", zap.String("url", r.URL.Path), zap.String("method", r.Method))
    handler(w, r)
    logger.Info("request completed", zap.String("path", r.URL.Path), zap.String("method", r.Method))
  }
}

func ExampleHandler(w http.ResponseWriter, r *http.Request) {
  w.Header().Add("Content-Type", "application/json")
  io.WriteString(w, `{"status":"ok"}`)
}
```

<div id="gin-application-example">
  ### Пример приложения Gin
</div>

В этом примере используется `gin-gonic/gin`.

```shell theme={null}
go get -u go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin
```

Обратитесь к разделам с комментариями, чтобы узнать, как настроить сбор телеметрии в вашем Go-приложении.

```go theme={null}

package main

import (
  "context"
  "log"
  "net/http"

  "github.com/gin-gonic/gin"
  "github.com/hyperdxio/opentelemetry-go/otelzap"
  "github.com/hyperdxio/opentelemetry-logs-go/exporters/otlp/otlplogs"
  sdk "github.com/hyperdxio/opentelemetry-logs-go/sdk/logs"
  "github.com/hyperdxio/otel-config-go/otelconfig"
  "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
  "go.opentelemetry.io/otel/trace"
  "go.uber.org/zap"
)

// добавить trace id к записи журнала
func WithTraceMetadata(ctx context.Context, logger *zap.Logger) *zap.Logger {
  spanContext := trace.SpanContextFromContext(ctx)
  if !spanContext.IsValid() {
    // ctx не содержит допустимого span.
    // Нет trace metadata для добавления.
    return logger
  }
  return logger.With(
    zap.String("trace_id", spanContext.TraceID().String()),
    zap.String("span_id", spanContext.SpanID().String()),
  )
}

func main() {
  // Инициализировать конфигурацию OTel и использовать её во всём приложении
  otelShutdown, err := otelconfig.ConfigureOpenTelemetry()
  if err != nil {
    log.Fatalf("error setting up OTel SDK - %e", err)
  }

  defer otelShutdown()

  ctx := context.Background()

  // настроить провайдер логгера OpenTelemetry
  logExporter, _ := otlplogs.NewExporter(ctx)
  loggerProvider := sdk.NewLoggerProvider(
    sdk.WithBatcher(logExporter),
  )

  // корректно завершить работу логгера для сброса накопленных сигналов перед завершением программы
  defer loggerProvider.Shutdown(ctx)

  // создать новый логгер с ядром OpenTelemetry zap и установить его глобально
  logger := zap.New(otelzap.NewOtelCore(loggerProvider))
  zap.ReplaceGlobals(logger)

  // Создать новый маршрутизатор Gin
  router := gin.Default()

  router.Use(otelgin.Middleware("service-name"))

  // Определить маршрут, обрабатывающий GET-запросы по корневому URL
  router.GET("/", func(c *gin.Context) {
    _logger := WithTraceMetadata(c.Request.Context(), logger)
    _logger.Info("Hello World!")
    c.String(http.StatusOK, "Hello World!")
  })

  // Запустить сервер на порту 7777
  router.Run(":7777")
}
```

<div id="configure-environment-variables">
  ### Настройте переменные окружения
</div>

После этого вам нужно задать в оболочке следующие переменные окружения, чтобы отправлять телеметрию в ClickStack через OpenTelemetry Collector:

<Tabs>
  <Tab title="Управляемый ClickStack">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    ```
  </Tab>

  <Tab title="ClickStack с открытым исходным кодом">
    ```shell theme={null}
    export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
    OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'
    ```
  </Tab>
</Tabs>

Переменная окружения `OTEL_EXPORTER_OTLP_HEADERS` содержит ключ API, доступный в приложении HyperDX в разделе `Team Settings → API Keys`.