> ## 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.
> ClickStack 向け Golang SDK - ClickHouse オブザーバビリティスタック
# Golang
ClickStack は、テレメトリーデータ (ログと
トレース) の収集に OpenTelemetry 標準を使用します。トレースは自動インストルメンテーションによって自動生成されるため、トレーシングの価値を得るのに手動の
インストルメンテーションは必要ありません。
**このガイドで統合される項目:**
## はじめに
### OpenTelemetry のインストルメンテーションパッケージをインストールする
OpenTelemetry と HyperDX の Go パッケージをインストールするには、以下のコマンドを使用します。トレース情報が正しく付与されるよう、[最新のインストルメンテーションパッケージ](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
```
### ネイティブな HTTP サーバーの例 (net/http)
この例では、`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),
)
}
// ログにトレースIDを付与する
func WithTraceMetadata(ctx context.Context, logger *zap.Logger) *zap.Logger {
spanContext := trace.SpanContextFromContext(ctx)
if !spanContext.IsValid() {
// ctx に有効なスパンが含まれていない。
// 追加するトレースメタデータが存在しない。
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())
}
}
// すべてのハンドラーをラップしてロガーにトレースメタデータを追加する際に使用する
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"}`)
}
```
### Gin アプリケーションの例
この例では、`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"
)
// ログにトレースIDを付与する
func WithTraceMetadata(ctx context.Context, logger *zap.Logger) *zap.Logger {
spanContext := trace.SpanContextFromContext(ctx)
if !spanContext.IsValid() {
// ctxに有効なスパンが含まれていない。
// 追加するトレースメタデータが存在しない。
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),
)
// プログラム終了前に蓄積されたシグナルをflushするため、ロガーをグレースフルシャットダウンする
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"))
// ルートURLへのGETリクエストに応答するルートを定義する
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")
}
```
### 環境変数を設定する
その後、OpenTelemetry collector 経由で ClickStack にテレメトリーを取り込むため、シェルで次の環境変数を設定する必要があります。
```shell theme={null}
export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_SERVICE_NAME='' \
```
```shell theme={null}
export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_SERVICE_NAME='' \
OTEL_EXPORTER_OTLP_HEADERS='authorization='
```
`OTEL_EXPORTER_OTLP_HEADERS` 環境変数には、HyperDX アプリの `Team Settings → API Keys` で利用できる API キーが含まれます。