Troubleshooting

To verify proper integration of the Go collector in your application, follow these steps:

1. Initialize the Go collector

   You must initialize the Go collector at the start of your application by using the InitCollector function from the Instana package:

   import (
       instana "github.com/instana/go-sensor"
   )
   
   func main() {
       // Initialize the collector with service name and other options
       collector := instana.InitCollector(&instana.Options{
           Service:           "your-service-name",
           EnableAutoProfile: true,
           Tracer:            instana.DefaultTracerOptions(),
       })
   
       // Your application code here
   }

   Key configuration options:

   • Service (required): Name of your service as it appears in Instana.
   • EnableAutoProfile (optional): Enables the automatic profiling feature.
   • Tracer (optional): Configures tracer options.
2. Verify collector connection

   After initialization, check your application logs for any connection issues. If the collector is properly connected to the Instana agent, no error messages is displayed.

3. Use instrumentation libraries

   For comprehensive monitoring, use Instana's instrumentation libraries to instrument specific components of your application. These libraries create spans and collect metrics for various operations.

   Instana provides several instrumentation libraries for popular Go packages.

   For more information, refer to the following available instrumentation libraries:

   • HTTP server instrumentation
   • SQL based DB instrumentation
   • GraphQL instrumentation
   • Redis instrumentation
   • MongoDB instrumentation
   • Kafka instrumentation
   • Other instrumentation packages
4. Set up proper environment variables

   Ensure that all necessary environment variables are correctly configured for your deployment scenario. Missing or incorrectly set environment variables can affect how the Instana Go tracer operates, leading to incomplete monitoring or configuration issues.

   For more details on required environment variables and their configuration, see the Configuring Go Collector section.

To resolve networking issues, troubleshoot as follows:

• Verify that the Go process can connect to the host agent on the same host on port 42699. For more information about the required network visibility, see Network requirements for the Instana host agent.

• In containerized platforms, check network visibility between the container with the application to be traced and the container of the Instana host agent. Ensure that no overlay network setup issue exists when the application container to be traced tries to connect to the Instana agent container on the same host.

• Ensure that the Go collector uses the correct IP address or DNS name to communicate to the Instana agent. If you need to change the network address, you can instruct the Go collector to use the INSTANA_AGENT_HOST environment variable.

• Ensure that the host agent is listening on port 42699. If you need a port remapping because the host agent does not listen on port 42699 but something else, you can configure the collector to use a different port by using the INSTANA_AGENT_PORT environment variable.

If none of the preceding solutions help you troubleshoot the issue, open a Support ticket.

Context propagation is the mechanism of passing trace information between different components of your application. In Go sensor, this propagation is primarily achieved through Go's context package by using instana.ContextWithSpan() and instana.SpanFromContext() .

The following example shows correctly propagating context from an HTTP endpoint to a SQL database operation:

import (
    "fmt"
    "io"
    "net/http"

    _ "github.com/go-sql-driver/mysql"
    instana "github.com/instana/go-sensor"
)

func main() {
    // Initialize the Instana collector
    col := instana.InitCollector(&instana.Options{
        Service: "your-service-name",
        Tracer:  instana.DefaultTracerOptions(),
    })

    // HTTP handler with SQL database operation
    http.HandleFunc("/api/users", instana.TracingHandlerFunc(col, "/api/users", func(w http.ResponseWriter, req *http.Request) {
        // Open an instrumented database connection
        db, err := instana.SQLInstrumentAndOpen(col, "mysql", "user:password@tcp(localhost:3306)/mydb")
        if err != nil {
            http.Error(w, "Database connection failed", http.StatusInternalServerError)
            return
        }
        defer db.Close()

        // The request context already contains the span from the HTTP handler
        ctx := req.Context()

        // Use the same context for the database query to maintain the trace
        rows, err := db.QueryContext(ctx, "SELECT id, name FROM users LIMIT 10")
        if err != nil {
            http.Error(w, "Query failed", http.StatusInternalServerError)
            return
        }
        defer rows.Close()

        // Process the query results
        var result string
        for rows.Next() {
            var id int
            var name string
            if err := rows.Scan(&id, &name); err != nil {
                continue
            }
            result += fmt.Sprintf("User: %d - %s\n", id, name)
        }

        io.WriteString(w, result)
    }))

    http.ListenAndServe(":8080", nil)
}

You need to adhere to the following best practices:

• Always pass the context: Pass the context containing the span to all operations that support context.

• Use context-aware methods: Use methods that accept a context parameter, such as QueryContext for databases or instrumented client methods.

• Extract and inject spans properly: When working with manual instrumentation, use SpanFromContext() to extract spans and ContextWithSpan() to inject them.

• Maintain context across goroutines: When spawning goroutines, pass the context to ensure trace continuity.

• Check instrumentation libraries: Use Instana's instrumentation libraries for popular packages, such as Redis, MongoDB, or SQL databases, as they handle context propagation automatically.

You need to avoid the following mistakes:

• Creating a new context instead of using the one from the request.
• Not passing the context to operations that support it.
• Using non-context-aware methods when context-aware alternatives exist.
• Losing context when crossing service boundaries.

By following these guidelines, you can ensure that your distributed traces are properly connected, providing complete visibility into your application's performance.

To ensure optimal performance and access to the latest features, verify that you're using the latest version of the Instana Go Tracer SDK:

1. Check your go.mod file for the current version:

   require (
       github.com/instana/go-sensor v1.x.y
   )

   Compare with the latest version available on GitHub or the Supported runtimes section.

2. Update to the latest version if needed:

   go get -u github.com/instana/go-sensor

The Instana Go Tracer SDK is designed to work with specific versions of Go. Check compatibility as follows:

1. Verify your current Go version:

   go version

2. Ensure your Go version is compatible with the Instana Go Tracer SDK version.

By ensuring you're using the latest compatible versions, you can avoid many common issues and take advantage of the latest features and improvements in the Instana Go Tracer SDK.

To collect debug logs, complete the following steps:

1. Enable debug logging by setting the following environment variables:

   export INSTANA_DEBUG=true
   export INSTANA_LOG_LEVEL=debug
    

2. Restart your application and reproduce the issue.

3. Collect the application logs with debug information.

To collect agent logs from different host environments, see the following sections:

Gather the following information about your environment:

• Application deployment type:

  • Kubernetes (include version and distribution)
  • Docker (include version)
  • Virtual machine
  • Bare metal
  • Serverless (AWS Lambda, Google Cloud Functions, and other cloud services)

• OS details:

  • Linux
  • macOS
  • Windows
  • Other OS
• Go runtime version: Run the following command to identify the version:

  go version
   

• Instana Go Tracer SDK version that you're using: Run the following command to identify the version:

  # Extract Instana Go Tracer SDK version
  grep "github.com/instana/go-sensor" go.mod > go-sensor-version.txt

• Name and version of Go Tracer instrumentation libraries that you're using:

  github.com/instana/go-sensor/instrumentation/instasql v1.x.y
  github.com/instana/go-sensor/instrumentation/instaredis v1.x.y
  # etc.

  Run the following command to extraxt the libraries:

  # Extract instrumentation libraries
  grep -r "github.com/instana/go-sensor/instrumentation" go.mod >> instrumentation-library-versions.txt