instana / go-sensor

IBM Instana Go Tracer [ ][pkg.go.dev] The IBM Instana Go Tracer is an SDK that collects traces, metrics, logs and provides profiling for Go applications. The tracer is part of the IBM Instana Observability tool set. Compatibility Supported Runtimes ----- • Go Collector **v1.73** or later supports Go **1.26** and **1.25**, and maintains compatibility with *Go 1.24 (EOL)* and *Go 1.23 (EOL)*. > [!NOTE] > Make sure to always use the latest version of the tracer, as it provides new features, improvements, security updates and fixes. Installation To add the tracer to your project, run: > [!NOTE] > As a good practice, add this command to your CI pipeline or your automated tool before building the application to keep the tracer up to date. Usage Initial Setup Once the tracer is added to the project, import the package into the entrypoint file of your application: Create a reference to the collector and initialize it with a service name: > [!NOTE] > The tracer expects the Instana Agent to be up and running in the default port 42699. You can change the port with the environment variable INSTANA_AGENT_PORT . > [!NOTE] > For non default options, like the Agent host and port, the tracer can be configured either via SDK options, environment variables or Agent options. Collecting Metrics Once the collector has been initialized with , application metrics such as memory, CPU consumption, active goroutine count etc will be automatically collected and reported to the Agent without further actions or configurations to the SDK. This data is then already available in the dashboard. Tracing Calls Let's collect traces of calls received by an HTTP server. Before any changes, your code should look something like this: Wrap the function with . Now your code should look like this: When running the application, every time is called, the tracer will collect this data and send it to the Instana Agent. You can monitor traces to this endpoint in the Instana UI. Profiling Unlike metrics, profiling needs to be enabled with the option, as seen here: You should be able to see your application profiling in the Instana UI under Analytics/Profiles. Logging In terms of logging, the SDK provides two distinct logging features: • Traditional logging, that is, logs reported to the standard output, usually used for debugging purposes • Instana logs, a feature that allows customers to report logs to the dashboard under Analytics/Logs Traditional Logging Traditional logs are **not available in the Instana dashboard**. These logs are written to the console output and are primarily used for debugging and troubleshooting purposes. The SDK provides many logs, usually prefixed with "INSTANA", which help you understand what the tracer is doing underneath. You can also generate your own logs by calling one of the following methods: • Collector.Info() • Collector.Warn() • Collector.Error() • Collector.Debug() You can control the log level via SDK options or the environment variable. If you're using the **default logger**: Logs are written to the standard console output (stdout/stderr). If you're using a **custom logger**: Logs are written to the destination configured in your custom logger implementation. > [!NOTE] > If you need logs to appear in the Instana dashboard under Analytics/Logs, use **Instana Logs** (described below) instead of traditional logging. You can find detailed information in the Instana documentation. Instana Logs Instana Logs are spans of the type that are rendered in a special format in the Instana dashboard under **Analytics/Logs**. You can create logs and report them to the agent or attach them as children of an existing span. Manual Log Creation The code snippet below shows how to manually create logs and send them to the agent: This log can then be visualized in the dashboard under Analytics/Logs. You can add a filter by service name. In our example, the service name is "My Go App". Logrus Integration The Go sensor provides an **instrumentation library for Logrus**, a popular structured logging library. The hook automatically collects warning and error logs from your Logrus logger, associates them with the current span, and sends them to Instana. For detailed information, see the instalogrus documentation. Opt-in Exit Spans Go tracer support the opt-in feature for the exit spans. When enabled, the collector can start capturing exit spans, even without an entry span. This capability is particularly useful for scenarios like cronjobs and other background tasks, enabling the users to tailor the tracing according to their specific requirements. By setting the variable, users can choose whether the tracer should start a trace with an exit span or not. The environment variable can have 2 values. (1: Tracer should record exit spans for the outgoing calls, when it has no active entry span. 0 or any other values: Tracer should not start a trace with an exit span). Complete Example Basic Usage Wrapping up Let's quickly summarize what we have seen so far: • We learned how to install, import and initialize the Instana Go Tracer. • Once the tracer is initialized, application metrics are collected out of the box. • Application profiling can be enabled via the option. • Tracing incoming HTTP requests by wrapping the Go standard library with . With this knowledge it's already possible to make your Go application traceable by our SDK. But there is much more you can do to enhance tracing for your application. The basic functionality covers tracing for the following standard Go features: • HTTP incoming requests • HTTP outgoing requests • SQL drivers As we already covered HTTP incoming requests, we suggest that you understand how to collect data from HTTP outgoing requests and SQL driver databases. Another interesting feature is the usage of additional packages located under instrumentation. Each of these packages provide tracing for specific Go packages like the AWS SDK, Gorm and F…