30 August 2018 Releases

Elastic APM Go Agent 0.5.0 Released

By Andrew Wilkins

Elastic is pleased to announce that version 0.5.0 of the Go agent for Elastic APM has been released, fixing several minor issues, improving existing features, and adding several new ones.

In the next release we will be changing the canonical import path prefix to “go.elastic.co/apm”, and the top-level package name to “apm”. Please consider vendoring if this will break your builds.

Major New Features

SQL parsing

Spans reported by module/apmsql are now given more informative names by parsing the SQL. The parser is designed to accommodate a variety of SQL dialects including MySQL, PostgreSQL, and T-SQL (Microsoft SQL Server).

For DDL statements (CREATE, DROP, ALTER, etc.), we continue to only report the first token, e.g. the statement “CREATE TABLE foo (...)” will be reported as a span named “CREATE”. Other statements are handled as follows:

Sample Statement Span Name
DELETE FROM table WHERE condition DELETE FROM table
INSERT INTO table (column) VALUES (value) INSERT INTO table
UPDATE table SET column=value WHERE condition UPDATE table
SELECT * FROM table WHERE condition SELECT FROM table
CALL my_function(args…) CALL my_function

Comments, quotes, joins, and sub-selects are all taken into account. Where joins or sub-selects are present in a SELECT statement, we use the name of the first table referenced in the outermost select expression. If the parser encounters something it cannot handle, we revert to reporting the first token of the SQL statement as before.

GORM instrumentation module

GORM is a popular object-relational mapping library for Go. We introduce module/apmgorm, which provides an API for instrumenting GORM database connections, tracing the SQL queries/statements executed. Many thanks to @Azuka from the community for providing helpful pointers and early testing.

See the module/apmgorm documentation for usage.

Cassandra instrumentation module

GoCQL is the most popular Go client for Cassandra. With this release, we introduce module/apmgocql, which provides an implementation of gocql’s batch and query observers, reporting them as spans to Elastic APM similarly to how we report database/sql operations. We also make use of the SQL parser mention above for forming the Cassandra span names.

See the module/apmgocql documentation for usage.

OpenTracing bridge (experimental)

We are working towards support for distributed tracing across all of the agents, as well as in the server and UI. In this release we introduce the foundations for the Go agent’s support for distributed tracing, as well as an initial experimental implementation of the OpenTracing API as an optional layer on top of the agent’s core API.

This is at very early stage, and is not yet 100% compliant or suitable for production. This implementation does not currently support baggage, logging, or a binary propagation format. For HTTP/text propagation formats, we are implementing the draft W3C Trace-Parent header, but with an alternative name to avoid conflicting with later changes to the draft. We will update this later, when Trace-Context progresses beyond draft.

Minor changes

You can find the full list of changes in the 0.5.0 release notes. Below are a few of the more noteworthy changes.

Go modules

We have introduced a go.mod file for go module (formerly vgo) support. We may later add finer-grained modules (e.g. one per instrumentation module package).

httprouter.Router wrapper

The apmhttprouter package provides the Wrap function for instrumenting an httprouter.Handle. This is a little cumbersome to use, as it requires passing in the route path to the Wrap function as well as when registering the route handler. To make this neater, we now also provide a Router type which wraps an httprouter.Router, instrumenting all routes added to it.

Configuration

We have redefined the default behaviour for ELASTIC_APM_SERVER_URL. Previously if you left this undefined, the tracer would be disabled. Now, to match the behaviour of the other agents, we default to sending data to http://localhost:8200.

We have introduced two configuration environment variables:

  • ELASTIC_APM_SERVER_TIMEOUT controls the amount of time the agent allows before requests to the APM server are abandoned. This defaults to 30 seconds.
  • ELASTIC_APM_IGNORE_URLS can be used to specify a regular expression matching the URLs of HTTP requests to ignore in the HTTP server middleware. Requests matching the regular expression will not be reported to Elastic APM.

Onward

We welcome you to follow along on GitHub, or join us in the Elastic APM Discuss forum. We would also love it if you filled out the Go agent survey, to help shape its future.