Go Collector: Häufig gestellte Fragen zu allgemeinen Vorgängen

Um den „ Go “-Collector zu initialisieren, rufen Sie instana.InitSensor() zu Beginn Ihrer main() Funktion den Aufruf auf und übergeben Sie dabei ein *instana.Options Konfigurationsobjekt:

import instana "github.com/instana/go-sensor"

func main() {
    instana.InitSensor(&instana.Options{
        // ...
    })

    // ...
}
 

Der „ Go “-Collector verwendet die Werte von instana.DefaultOptions() für nicht initialisierte Felder des Konfigurationsobjekts, das der instana.InitSensor() Funktion übergeben wird.

Um sicherzustellen, dass Go Collector den Ankündigungsvorgang abgeschlossen hat und bereit ist, Traces zu erfassen, bevor der Datenverkehr an eine Instanz gesendet wird, verwenden Sie die folgende instana.Ready() Methode:

// Every 100ms whether Go Collector is ready and return on success
func awaitInstanaReady(ctx context.Context) error {
    ticker := time.NewTicker(100*time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            if instana.Ready() {
                return nil
            }
        case <-ctx.Done():
            return ctx.Err()
        }
    }

    return nil
}
 

Um sicherzustellen, dass alle erfassten Traces an den Host-Agenten oder den serverlosen Acceptor gesendet wurden, bietet der „ Go “-Collector API die instana.Flush() Methode an. Diese Methode zwingt den Agentenclient, alle gepufferten Daten sofort zu senden. Es handelt sich um eine blockierende Operation. Es wird empfohlen, ein Zeitlimit oder einen Termin für diese Operation zu definieren, damit Ihr Service ordnungsgemäß beendet werden kann:

func main() {
    var srv http.Server

    // Initialize and use http.Server
    // ...

    // Server shutdown sequence:
    // 1. Finalize all pending requests and close the server
    shutdownCtx, _ := context.WithTimeout(ctx, 5 * time.Second)
    if err := srv.Shutdown(shutdownCtx); err != nil {
        // ...
    }
    // 2. Flush all buffered traces to the agent
    flushCtx, _ := context.WithTimeout(ctx, 5 * time.Second)
    if err := instana.Flush(flushCtx); err != nil {
        // ...
    }
    // ...
}
 

Wenn ein Dienst unter AWS Lambda läuft, instana.Flush() wird dieser automatisch vom „ Go “-Collector aufgerufen, sobald der Handler fertig ist; es ist also nicht erforderlich, dies manuell zu tun.

Um Go Collector für die Überwachung eines Services zu verwenden, der in einer serverunabhängigen Umgebung ausgeführt wird, wie AWS Fargate oder Google Cloud Run, stellen Sie sicher, dass Sie die Umgebungsvariablen INSTANA_ENDPOINT_URL und INSTANA_AGENT_KEY in Ihrer Taskdefinition eingestellt haben. Ausführliche Erläuterungen zur Vorgehensweise finden Sie im entsprechenden Abschnitt der Instana-Dokumentation:

• Konfigurieren von Aufgaben-Definitionen für „ AWS Fargate “
• AWS Lambda -Funktionen konfigurieren
• Google Cloud Run -Dienste konfigurieren

Dienste, die in serverlosen Umgebungen ausgeführt werden, verwenden keinen Host-Agenten, um Metriken und Trace-Daten an das Backend von „ Instana “ zu senden; daher ist die übliche Vorgehensweise zur Konfiguration des In-App-Collectors über configuration.yaml eine Konfigurationsdatei hier nicht anwendbar. Stattdessen gibt es eine Gruppe von Umgebungsvariablen, die optional in der Service-Taskdefinition konfiguriert werden können:

Eine ausführlichere Beschreibung dieser Variablen und ihres Werteformats finden Sie in der Dokumentation unter Instana.

Bestimmte von Instana bereitgestellte Wrapper für die Instrumentierung, z. B. die HTTP-Server- und Client-Wrapper, erfassen Daten, die vertrauliche Informationen wie Kennwörter, Schlüssel und geheime Schlüssel enthalten können. Um ein Durchsickern dieser Werte zu vermeiden, ersetzt der „ Go “-Collector sie durch, <redacted> bevor er sie an den Agenten sendet. Die Liste der Parameternamen-Matcher ist im com.instana.secrets Abschnitt der Host-Agent-Konfigurationsdatei definiert und wird während der Ankündigungsphase an den In-App-Tracer gesendet (erfordert das Trace-Plugin „Agent- Gocom.instana.sensor-golang-trace “ v1.3.0 und höher).

Die Standardeinstellung für die Abgleichkomponente für geheime Schlüssel ist contains-ignore-case mit der folgenden Liste von Begriffen: key, password, secret. Dies würde den Wert eines Parameters neu bearbeiten, dessen Name eine dieser Zeichenfolgen enthält, wobei die Groß-/Kleinschreibung ignoriert wird.

Die Instrumentierungs-Wrapper von „ HTTP “ können „ HTTP “-Header erfassen und diese zusammen mit den eingehenden oder ausgehenden Request-Spans senden. Die Liste der groß-/kleinschreibungsunabhängigen Header-Namen kann sowohl im Feld (instana.Options).Tracer.CollectableHTTPHeaders des Optionsobjekts, das an übergeben wird, als auch instana.InitSensor() in der Host-Agent-Konfigurationsdatei angegeben werden. Die letztgenannte Einstellung hat Vorrang und erfordert das Agent- Go -Trace-Plugin com.instana.sensor-golang-tracev1.3.0 oder eine neuere Version:

instana.InitSensor(&instana.Options{
        // ...
        Tracer: instana.TracerOptions{
                // ...
                CollectableHTTPHeaders: []string{"x-request-id", "x-loadtest-id"},
        },
})
 

Diese Konfiguration entspricht den folgenden Einstellungen in der Konfigurationsdatei des Host-Agenten :

com.instana.tracing:
  extra-http-headers:
    - 'x-request-id'
    - 'x-loadtest-id'
 

Die HTTP-Instrumentierung erfasst standardmäßig keine Header.

Sie können den „ Go “-Collector so konfigurieren, dass er einen Logger eines Drittanbieters verwendet, der der instana.LeveledLogger Schnittstelle entspricht. Verwenden Sie go.uber.org/zap beispielsweise für github.com/sirupsen/logrus oder die Methode [ instana.SetLogger()][ instana.SetLogger ]:

import (
    "github.com/uber-go/zap"
    instana "github.com/instana/go-sensor"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    instana.SetLogger(logger)
}
 

Damit der Go Collector Debugprotokolle schreiben kann, ohne den App-Code zu ändern, setzen Sie die Umgebungsvariable INSTANA_DEBUG auf einen nicht leeren Wert, zum Beispiel:

export INSTANA_DEBUG=true
./your-app
 

Die Menge der Debugprotokolle, die Go Collector erzeugt, hängt von Ihrer Anwendung ab und kann erheblich sein. Es wird empfohlen, die Debug-Protokolle vorübergehend zu aktivieren, um Informationen zu sammeln, bevor Sie ein Problem an den Instana -Support melden.

Instana Go Collector bietet einen Instrumentierungs-Wrapper für github.com/sirupsen/logrus , um Fehler- und Warnprotokolleinträge automatisch zu erfassen und an den Agenten zu senden. github.com/instana/go-sensor/instrumentation/instalogrus bietet eine Implementierung, logrus.Hook die alle Fehler- oder Warnungsdatensätze verarbeitet und diese dem im Datensatz enthaltenen Span context.Context zuordnet. Das folgende Beispiel zeigt, wie die globale logrus.Loggerinstrumentiert und innerhalb der instrumentierten http.Handlerverwendet werden kann:

func main() {
        // ...

        // Register instalogrus hook within the global logger
        logrus.AddHook(instalogrus.NewHook(sensor))
}

func myMethod(w http.ResponseWriter, req *http.Request) {
        // ...

    // When logging an error, make sure to provide the context.Context containing
    // an active span, so that instrumentation hook could associate this message
    // with a call.
    logrus.WithContext(req.Context()).Error("something went wrong")

    // ...
}
 

Ausführlichere Beispiele finden Sie in der Dokumentation zum Paket.

Um das kontinuierliche Profiling für Ihren Service dauerhaft zu aktivieren, stellen Sie EnableAutoProfile: true bereit, während Sie den Sensor initialisieren:

func main() {
    instana.InitSensor(&instana.Options{
                EnableAutoProfile: true,
                // ... other options
        })

        // ...
}
 

Um „ AutoProfile™ “ vorübergehend über Ihren Code zu aktivieren oder zu deaktivieren, rufen Sie und autoprofile.Enable() auf: autoprofile.Disable()

func expensiveCalculation() {
    autoprofile.Enable()
    defer autoprofile.Disable()

    // ...
}
 

Um „ AutoProfile™ “ für eine App ohne Codeänderungen zu aktivieren, setzen Sie die INSTANA_AUTO_PROFILE=true Umgebungsvariable:

export INSTANA_AUTO_PROFILE=true
./your-app
 

Mit Unterstützung für das Wrapping einer http.HandlerFunc fügt Instana schnell die Möglichkeit hinzu, Anforderungen zu verfolgen und untergeordnete Spans zu erfassen, die im Kontext des Anforderungsspans ausgeführt werden.

Damit Instana die erforderlichen Informationen erfassen kann, sind nur minimale Änderungen erforderlich. Durch einfaches Einschließen der aktuell vorhandenen http.HandlerFunc erfasst und fügt Instana die erforderlichen Informationen automatisch ein.

Das heißt, eine einfache Handlerfunktion wie die folgende wird einfach eingeschlossen und wie üblich registriert.

Der folgende Beispielcode zeigt, wie ein HTTP-Handler mithilfe von instana.TracingHandlerFunc() instrumentiert werden kann:

sensor := instana.NewSensor("my-http-server")

http.HandleFunc("/", instana.TracingHandlerFunc(sensor, "/", func(w http.ResponseWriter, req *http.Request) {
        // ...
}))
 

Falls Ihr Handler als http.Handler implementiert ist, übergeben Sie stattdessen dessen ServeHTTP-Methode:

h := http.FileServer(http.Dir("./"))
http.HandleFunc("/files", instana.TracingHandlerFunc(sensor, "index", h.ServeHTTP))
 

Das vollständige Beispiel example/http-database-greeter finden Sie unter.

Die Anforderung von Daten oder Informationen von anderen, oft externen Systemen, wird üblicherweise durch HTTP-Anforderungen implementiert. Um sicherzustellen, dass Traces alle Spans enthalten, insbesondere über alle verschiedenen Systeme hinweg, müssen bestimmte Spaninformationen in die Header der HTTP-Anforderung eingefügt werden, bevor sie gesendet werden. Der „ Go “-Collector von Instana bietet Unterstützung, um diesen Prozess so weit wie möglich zu automatisieren.

Damit Instana Informationen in die Anforderungsheader einfügt, erstellen Sie den http.Client, schließen Sie dessen Transport mit instana.RoundTripper() ein und verwenden Sie ihn wie im folgenden Beispiel.

req, err := http.NewRequest("GET", url, nil)
client := &http.Client{
        Transport: instana.RoundTripper(sensor, nil),
}

ctx := instana.ContextWithSpan(context.Background(), parentSpan)
resp, err := client.Do(req.WithContext(ctx))
 

Das bereitgestellte Objekt parentSpan ist die eingehende Anfrage vom Request-Handler (siehe das vorangehende Beispiel) und enthält die erforderlichen Trace- und Span-Informationen, um einen untergeordneten Span zu erstellen und diesen in die Anfrage einzufügen.

Um einen Datenbanktreiber zu instrumentieren, müssen Sie ihn zunächst mithilfe von instana.InstrumentSQLDriver() registrieren und den Aufruf von sql.Open() durch instana.SQLOpen() ersetzen. Hier ist ein Beispiel dafür, wie man dies für den github.com/lib/pq PostgreSQL-Treiber durchführt:

// Create a new instana.Sensor instance
sensor := instana.NewSensor("my-database-app")

// Instrument the driver
instana.InstrumentSQLDriver(sensor, "postgres", &pq.Driver{})

// Create an instance of *sql.DB to use for database queries
db, err := instana.SQLOpen("postgres", "postgres://...")
 

Der instrumentierte Treiber wird unter dem Namen <original_name>_with_instanaregistriert, z. B. wäre der Name im postgres_with_instanavorangegangenen Beispiel.

Das vollständige Beispiel example/http-database-greeter finden Sie unter.

Das Starten von Go v1.10 database/sql stellt einen neuen Weg zur Initialisierung von *sql.DB bereit, der nicht die Verwendung der globalen Treiberregistry erfordert. Wenn die Datenbanktreiberbibliothek einen Typ bereitstellt, der die Schnittstelle database/sql/driver.Connector erfüllt, kann sie verwendet werden, um eine Verbindung zur Datenbank herzustellen.

Um eine driver.Connector -Instanz zu instrumentieren, schließen Sie sie mit instana.WrapSQLConnector()ein. Hier ist ein Beispiel dafür, wie dies für github.com/go-sql-driver/mysql/ MySQL-Treiber durchgeführt werden kann:

// Create a new instana.Sensor instance
sensor := instana.NewSensor("my-database-app")

// Initialize a new connector
connector, err := mysql.NewConnector(cfg)
// ...

// Wrap the connector before passing it to sql.OpenDB()
db, err := sql.OpenDB(instana.WrapSQLConnector(sensor, "mysql://...", connector))
 

Das github.com/instana/go-sensor/instrumentation/instamongo Modul stellt Konstruktormethoden bereit, die eine neue Instanz von go.mongodb.org/mongo-driver `client` erstellen und diese mit ` Instana ` instrumentieren.

Ausführliche Beispiele und Anleitungen zur Verwendung finden Sie in der Dokumentation des Pakets.

1. Das github.com/instana/go-sensor/instrumentation/instaredis Modul bietet Funktions-Wrapper für go-redis dieses Instrument, eine Instanz von redis.Client oder, redis.ClusterClient indem es Hooks zum „ redis “-Client hinzufügt.

   Ausführliche Beispiele und Anleitungen zur Verwendung finden Sie in der Dokumentation des Pakets.

2. Das github.com/instana/go-sensor/instrumentation/instaredigo Modul bietet Wrapper für redigo dieses Instrument, eine Instanz von redis.Conn.

   Ausführliche Beispiele und Anleitungen zur Verwendung finden Sie in der Dokumentation des Pakets.

Das github.com/instana/go-sensor/instrumentation/instagrpc Modul bietet sowohl Stream- als auch unäre Aufruf-Interceptoren. Die Moduldokumentation enthält eine ausführliche Anleitung dazu, wie man damit einen mit implementierten google.golang.org/grpcgRPC -Server instrumentieren kann.

Das vollständige Beispiel example/grpc-client-server finden Sie unter.

Das github.com/instana/go-sensor/instrumentation/instagrpc Modul bietet sowohl Stream- als auch unäre Aufruf-Interceptoren. Die Moduldokumentation enthält eine ausführliche Anleitung dazu, wie man damit einen mit implementierten „ google.golang.org/grpcgRPC “-Client instrumentieren kann.

Das vollständige Beispiel example/grpc-client-server finden Sie unter.

Das github.com/instana/go-sensor/instrumentation/instasarama Modul stellt Konstruktormethoden bereit, die eine neue Instanz von Producer-Consumer-Clients erstellen und diese mit „ Instana “ ausstatten.

Das vollständige Beispiel example/kafka-producer-consumer finden Sie unter.

Das github.com/instana/go-sensor/instrumentation/instaamqp Modul bietet einen Funktions-Wrapper, amqp.Channel der eine instaamqp.AmqpChannel Instanz zurückgibt. Dieses Objekt „ Instana “ bietet Instrumentierungsfunktionen für die Methoden amqp.Channel.Publish amqp.Channel.Consume und, die für die Nachverfolgung von Daten aus gesendeten und empfangenen Nachrichten zuständig sind.

Das vollständige Beispiel finden Sie unter github.com/instana/go-sensor/blob/main/instrumentation/instaamqp .

Eine minimale Instrumentierung einer Methode mit Go Collector besteht aus zwei Schritten:

1. Beginne einen neuen Abschnitt mit instana.Sensor .
2. Schließen Sie den Bereich ab, bevor die Methode zurückgegeben wird.

Optionale Schritte umfassen das Erfassen der Details, die für diesen Aufruf relevant sind, um sie an den aktiven Bereich anzuhängen, und das Einfügen des aktiven Bereichs in context.Context , um die Tracefortsetzungsicherzustellen.

func MyMethod(sensor *instana.Sensor) {
    // Start a new span associated with this method execution
    span := sensor.Tracer().StartSpan("my-method")
    // Schedule span finalization to send it to Instana agent
    defer span.Finish()

    // Optionally attach any relevant information that would help you to identify this call later
    span.SetTag("key1", "value1")
    span.SetTag("answer", 42)

    // ...
}
 

Ein ausführlicheres Beispiel example/opentracing finden Sie unter.

Um einen Unteraufruf einem aktiven Span zuzuordnen, stellen Sie dessen Kontext über die Startspanoption opentracing.ChildOf() bereit, wenn Sie den Unteraufrufspan starten:

var spanOpts []opentracing.StartSpanOption

// Check whether there is an active trace by fetching the currently active span from context
if parent, ok := instana.SpanFromContext(ctx); ok {
    spanOpts = append(spanOpts, opentracing.ChildOf(parent.Context()))
}

// Start the subcall span
span := tracer.StartSpan("my-func", spanOpts...)
 

Es liegt in der Verantwortung des Aufrufers, sicherzustellen, dass eine Instanz von, die dem context.Context Aufgerufenen übergeben wird, den aktiven Bereich enthält, in den instana.ContextWithSpan() eingespeist wurde:

// And inject it into context, so any subcalls could use it as a parent
SubCall(instana.ContextWithSpan(ctx, span))
 

Die von Instana bereitgestellten Code-Wrapper nutzen, context.Context um die übergeordnete Span in einen Unteraufruf einzufügen. Das heißt, innerhalb einer instrumentierten Handler-/Callback-Funktion kann man davon ausgehen, dass instana.SpanFromContext() die Span zurückgibt, die von der Wrapper-Methode gestartet wurde:

parentSpan, ok := instana.SpanFromContext(ctx)