Activer les signaux de télémétrie dans les bibliothèques clientes Go

Google Cloud fournit des fonctionnalités puissantes de surveillance, de journalisation et de diagnostic pour les applications Go.

Les bibliothèques clientes Go sont instrumentées pour émettre des données de traçage, de métriques et de journalisation. L'instrumentation est facultative. Vous devez l'activer explicitement. Ce document décrit les signaux disponibles et explique comment les activer.

Signaux disponibles

Les signaux incluent les données de télémétrie suivantes, conformément aux conventions sémantiques OpenTelemetry :

• Traces : traces HTTP/gRPC de bas niveau représentant les requêtes réseau effectuées par les bibliothèques clientes.
• Métriques : métriques de requêtes client, qui suivent la latence et les taux de requêtes. La métrique principale est gcp.client.request.duration.
• Journaux : journaux d'erreurs exploitables au niveau DEBUG (et supérieur), fournissant des détails sur les requêtes ayant échoué au niveau du transport, même si elles sont finalement réessayées avec succès.

Les signaux incluent des attributs OpenTelemetry standards (par exemple, http.response.status_code et rpc.system.name) et des attributs personnalisés spécifiques à Google Cloud, qui peuvent inclure les attributs suivants et d'autres similaires :

• gcp.client.service : nom du service (par exemple, pubsub ou storage).
• gcp.client.repo : dépôt de la bibliothèque cliente (par exemple, googleapis/google-cloud-go).
• gcp.client.version : version de la bibliothèque cliente.
• gcp.client.artifact : chemin d'accès au module spécifique (par exemple, cloud.google.com/go/secretmanager).
• gcp.resource.destination.id : ID de la ressource concernée par l'action.
• gcp.errors.domain : domaine d'erreur pour les journaux d'erreurs exploitables.
• gcp.errors.metadata.<key> : clés de métadonnées d'erreur supplémentaires pour les requêtes ayant échoué (aplaties).

Pour obtenir la liste complète des attributs standards, consultez les conventions sémantiques OpenTelemetry HTTP et gRPC.

Activer la télémétrie

Pour protéger les données sensibles, les signaux d'or sont désactivés par défaut. Vous devez les activer explicitement.

Les traces, les journaux ou les métriques peuvent contenir des données sensibles telles que des noms de ressources, des URL complètes et des messages d'erreur.

Avant de configurer des abonnés ou des exportateurs pour les traces, les journaux ou les métriques, examinez le contenu des spans et des journaux, puis consultez la documentation OpenTelemetry et slog pour configurer des filtres et des formateurs afin d'éviter la fuite d'informations sensibles, en fonction de votre cas d'utilisation.

En Go, utilisez les variables d'environnement suivantes pour activer les traces, les métriques et les journaux de manière globale dans vos bibliothèques clientes Google Cloud  :

# Enable trace generation (span emission)
export GOOGLE_SDK_GO_TRACING=true

# Enable metrics
export GOOGLE_SDK_GO_METRICS=true

# Enable logging
export GOOGLE_SDK_GO_LOGGING=true

Propagation du contexte de trace

Les bibliothèques clientes Go propagent automatiquement les contextes de trace actifs aux servicesGoogle Cloud , même si la génération de traces (GOOGLE_SDK_GO_TRACING) est désactivée.

Si votre application comporte une portée OpenTelemetry active dans le context.Context transmis à une méthode de bibliothèque cliente, la bibliothèque l'utilise pour fournir un contexte de traçage pour les requêtes sortantes. Cela garantit que les traces au niveau de votre application peuvent être corrélées avec les journaux et les comportements des service de backend sans que vous ayez à émettre des spans côté client.

Configurez un propagateur de carte de texte OpenTelemetry global dans votre application pour fournir un contexte de traçage aux bibliothèques clientes.

Exporter la télémétrie

Une fois la télémétrie activée dans les bibliothèques clientes, votre application doit être configurée pour collecter et exporter ces données vers votre backend d'observabilité.

Traçage et métriques

Pour exporter les traces et les métriques générées par les bibliothèques clientes Go, initialisez le SDK OpenTelemetry avec l'exportateur de votre choix (par exemple, OTLP) et configurez le propagateur de carte de texte globale dans votre main.go :

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    ctx := context.Background()

    // Initialize the exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Set up the tracer provider
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    defer func() {
        // Ensure all spans are flushed before exit
        if err := tp.Shutdown(ctx); err != nil {
            log.Fatalf("failed to shutdown TracerProvider: %v", err)
        }
    }()

    otel.SetTracerProvider(tp)

    // Set up the global propagator
    otel.SetTextMapPropagator(propagation.TraceContext{})

    // ... initialize Google Cloud client libraries ...
}

Pour en savoir plus sur la connexion du SDK OpenTelemetry à Cloud Monitoring ou Cloud Trace, consultez les guides Google Cloud Observability pour Go.

Journalisation

Les bibliothèques clientes Go utilisent la journalisation structurée avec slog pour émettre des erreurs exploitables au niveau DEBUG. Les journaux exportés incluent automatiquement les ID de trace et les ID de portée si votre framework de journalisation est configuré pour les extraire de context.Context.

Pour recevoir ces journaux, vous devez fournir un *slog.Logger configuré au client lors de l'initialisation (par exemple, en utilisant option.WithLogger()).

Pour acheminer ces journaux structurés vers Cloud Logging, configurez slog pour écrire du code JSON dans la sortie standard (stdout). Si vous effectuez un déploiement dans un environnement tel que Google Kubernetes Engine ou Cloud Run, les agents intégrés récupèrent automatiquement ces journaux.

package main

import (
    "context"
    "log/slog"
    "os"

    "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
)

func main() {
    ctx := context.Background()

    // Configure slog to output JSON to stdout at the DEBUG level
    opts := &slog.HandlerOptions{Level: slog.LevelDebug}
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // Provide the logger to the client
    client, err := secretmanager.NewClient(ctx, option.WithLogger(logger))
    if err != nil {
        // handle error
    }
    defer client.Close()
}

Pour obtenir d'autres instructions sur le mappage des contextes de trace OpenTelemetry et la mise en forme des journaux JSON structurés afin de les aligner sur les champs de charge utile attendus de Cloud Logging, consultez Configurer la journalisation structurée pour Go.