diff --git a/docs/api.asciidoc b/docs/api.asciidoc deleted file mode 100644 index 6f46e38a9..000000000 --- a/docs/api.asciidoc +++ /dev/null @@ -1,607 +0,0 @@ -[[api]] -== API Documentation - -This section describes the most commonly used parts of the API. - -The Go agent is documented using standard godoc. For complete documentation, -refer to the documentation at https://pkg.go.dev/go.elastic.co/apm/v2[pkg.go.dev/go.elastic.co/apm/v2], -or by using the "godoc" tool. - -[float] -[[tracer-api]] -=== Tracer API - -The initial point of contact your application will have with the Go agent -is the `apm.Tracer` type, which provides methods for reporting -transactions and errors. - -To make instrumentation simpler, the Go agent provides an initialization -function, `apm.DefaultTracer()`. This tracer is initialized the first time -`apm.DefaultTracer()` is called, and returned on subsequent calls. The tracer -returned by this function can be modified using `apm.SetDefaultTracer(tracer)`. -Calling this will close the previous default tracer, if any exists. This -tracer is configured with environment variables; see <> for -details. - -[source,go] ----- -import ( - "go.elastic.co/apm/v2" -) - -func main() { - tracer := apm.DefaultTracer() - ... -} ----- - -// ------------------------------------------------------------------------------------------------- - -[float] -[[transaction-api]] -=== Transactions - -[float] -[[tracer-api-start-transaction]] -==== `func (*Tracer) StartTransaction(name, type string) *Transaction` - -StartTransaction returns a new Transaction with the specified name and type, -and with the start time set to the current time. If you need to set the -timestamp or the parent <>, use -<>. - -This method should be called at the beginning of a transaction such as a web -or RPC request. e.g.: - -[source,go] ----- -transaction := apm.DefaultTracer().StartTransaction("GET /", "request") ----- - -Transactions will be grouped by type and name in the Elastic APM app. - -After starting a transaction, you can record a result and add context to -further describe the transaction. - -[source,go] ----- -transaction.Result = "Success" -transaction.Context.SetLabel("region", "us-east-1") ----- - -See <> for more details on setting transaction context. - -[float] -[[tracer-api-start-transaction-options]] -==== `func (*Tracer) StartTransactionOptions(name, type string, opts TransactionOptions) *Transaction` - -StartTransactionOptions is essentially the same as StartTransaction, but -also accepts an options struct. This struct allows you to specify the -parent <> and/or the transaction's start time. - -[source,go] ----- -opts := apm.TransactionOptions{ - Start: time.Now(), - TraceContext: parentTraceContext, -} -transaction := apm.DefaultTracer().StartTransactionOptions("GET /", "request", opts) ----- - -[float] -[[transaction-end]] -==== `func (*Transaction) End()` - -End enqueues the transaction for sending to the Elastic APM server. -The transaction must not be modified after this, but it may still -be used for starting spans. - -The transaction's duration is calculated as the amount of time -elapsed between the start of the transaction and this call. To override -this behavior, the transaction's `Duration` field may be set before -calling End. - -[source,go] ----- -transaction.End() ----- - -[float] -[[transaction-tracecontext]] -==== `func (*Transaction) TraceContext() TraceContext` - -TraceContext returns the transaction's <>. - -[float] -[[transaction-ensureparent]] -==== `func (*Transaction) EnsureParent() SpanID` - -EnsureParent returns the transaction's parent span ID--generating and recording one if -it did not previously have one. - -EnsureParent enables correlation with spans created by the JavaScript Real User Monitoring -(RUM) agent for the initial page load. If your backend service generates the HTML page -dynamically, you can inject the trace and parent span ID into the page in order to initialize -the JavaScript RUM agent, such that the web browser's page load appears as the root of the -trace. - -[source,go] ----- -var initialPageTemplate = template.Must(template.New("").Parse(` - - - - - -... - -`)) - -func initialPageHandler(w http.ResponseWriter, req *http.Request) { - err := initialPageTemplate.Execute(w, apm.TransactionFromContext(req.Context())) - if err != nil { - ... - } -} ----- - -See the {apm-rum-ref}/index.html[JavaScript RUM agent documentation] for more information. - -[float] -[[transaction-parentid]] -==== `func (*Transaction) ParentID() SpanID` - -ParentID returns the ID of the transaction's parent, or a zero (invalid) SpanID if the transaction has no parent. - -[float] -[[apm-context-with-transaction]] -==== `func ContextWithTransaction(context.Context, *Transaction) context.Context` - -ContextWithTransaction adds the transaction to the context, and returns the resulting context. - -The transaction can be retrieved using <>. -The context may also be passed into <>, which uses -TransactionFromContext under the covers to create a span as a child of the transaction. - -[float] -[[apm-transaction-from-context]] -==== `func TransactionFromContext(context.Context) *Transaction` - -TransactionFromContext returns a transaction previously stored in the context using -<>, or nil if the context -does not contain a transaction. - -[float] -[[apm-detached-context]] -==== `func DetachedContext(context.Context) context.Context` - -DetachedContext returns a new context detached from the lifetime of the input, but -which still returns the same values as the input. - -DetachedContext can be used to maintain trace context required to correlate events, -but where the operation is "fire-and-forget" and should not be affected by the -deadline or cancellation of the surrounding context. - -[float] -[[apm-traceformatter]] -==== `func TraceFormatter(context.Context) fmt.Formatter` - -TraceFormatter returns an implementation of https://golang.org/pkg/fmt/#Formatter[fmt.Formatter] -that can be used to format the IDs of the transaction and span stored in the provided context. - -The formatter understands the following formats: - - - %v: trace ID, transaction ID, and (if in the context of a span) span ID, space separated - - %t: trace ID only - - %x: transaction ID only - - %s: span ID only - -The "+" option can be used to format the values in "key=value" style, with the field -names `trace.id`, `transaction.id`, and `span.id`. For example, using "%+v" as the format -would yield "trace.id=... transaction.id=... span.id=...". - -For a more in-depth example, see <>. - -// ------------------------------------------------------------------------------------------------- - -[float] -[[span-api]] -=== Spans - -To describe an activity within a transaction, we create spans. The Go agent -has built-in support for generating spans for some activities, such as -database queries. You can use the API to report spans specific to your -application. - -[float] -[[transaction-start-span]] -==== `func (*Transaction) StartSpan(name, spanType string, parent *Span) *Span` - -StartSpan starts and returns a new Span within the transaction, with the specified name, -type, and optional parent span, and with the start time set to the current time. -If you need to set the timestamp or parent <>, -use <>. - -If the span type contains two dots, they are assumed to separate the span type, subtype, -and action; a single dot separates span type and subtype, and the action will not be set. - -If the transaction is sampled, then the span's ID will be set, and its stacktrace will -be set if the tracer is configured accordingly. If the transaction is not sampled, then -the returned span will be silently discarded when its End method is called. To avoid any unnecessary computation for these dropped spans, call the <> -method. - -As a convenience, it is valid to create a span on a nil Transaction; the resulting span -will be non-nil and safe for use, but will not be reported to the APM server. - -[source,go] ----- -span := tx.StartSpan("SELECT FROM foo", "db.mysql.query", nil) ----- - -[float] -[[transaction-start-span-options]] -==== `func (*Transaction) StartSpanOptions(name, spanType string, opts SpanOptions) *Span` - -StartSpanOptions is essentially the same as StartSpan, but also accepts an options struct. -This struct allows you to specify the parent <> and/or the -spans's start time. If the parent trace context is not specified in the options, then the -span will be a direct child of the transaction. Otherwise, the parent trace context should -belong to some span descended from the transaction. - -[source,go] ----- -opts := apm.SpanOptions{ - Start: time.Now(), - Parent: parentSpan.TraceContext(), -} -span := tx.StartSpanOptions("SELECT FROM foo", "db.mysql.query", opts) ----- - -[float] -[[apm-start-span]] -==== `func StartSpan(ctx context.Context, name, spanType string) (*Span, context.Context)` - -StartSpan starts and returns a new Span within the sampled transaction and parent span -in the context, if any. If the span isn't dropped, it will be included in the resulting -context. - -[source,go] ----- -span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query") ----- - -[float] -[[span-end]] -==== `func (*Span) End()` - -End marks the span as complete. The Span must not be modified after this, -but may still be used as the parent of a span. - -The span's duration will be calculated as the amount of time elapsed -since the span was started until this call. To override this behaviour, -the span's Duration field may be set before calling End. - -[float] -[[span-dropped]] -==== `func (*Span) Dropped() bool` - -Dropped indicates whether or not the span is dropped, meaning it will not be reported to -the APM server. Spans are dropped when the created with a nil, or non-sampled transaction, -or one whose max spans limit has been reached. - -[float] -[[span-tracecontext]] -==== `func (*Span) TraceContext() TraceContext` - -TraceContext returns the span's <>. - -[float] -[[apm-context-with-span]] -==== `func ContextWithSpan(context.Context, *Span) context.Context` - -ContextWithSpan adds the span to the context and returns the resulting context. - -The span can be retrieved using <>. -The context may also be passed into <>, which uses -SpanFromContext under the covers to create another span as a child of the span. - -[float] -[[apm-span-from-context]] -==== `func SpanFromContext(context.Context) *Span` - -SpanFromContext returns a span previously stored in the context using -<>, or nil if the context -does not contain a span. - -[float] -[[span-parentid]] -==== `func (*Span) ParentID() SpanID` - -ParentID returns the ID of the span's parent. - -// ------------------------------------------------------------------------------------------------- - -[float] -[[context-api]] -=== Context - -When reporting transactions and errors you can provide context to describe -those events. Built-in instrumentation will typically provide some context, -e.g. the URL and remote address for an HTTP request. You can also provide -custom context and tags. - -[float] -[[context-set-label]] -==== `func (*Context) SetLabel(key string, value interface{})` - -SetLabel labels the transaction or error with the given key and value. -If the key contains any special characters (`.`, `*`, `"`), they will be -replaced with underscores. - -If the value is numerical or boolean, then it will be sent to the server -as a JSON number or boolean; otherwise it will converted to a string, using -`fmt.Sprint` if necessary. Numerical and boolean values are supported by -the server from version 6.7 onwards. - -String values longer than 1024 characters will be truncated. Labels are -indexed in Elasticsearch as keyword fields. - -TIP: Before using labels, ensure you understand the different types of -{apm-guide-ref}/data-model-metadata.html[metadata] that are available. - -WARNING: Avoid defining too many user-specified labels. -Defining too many unique fields in an index is a condition that can lead to a -{ref}/mapping.html#mapping-limit-settings[mapping explosion]. - -[float] -[[context-set-custom]] -==== `func (*Context) SetCustom(key string, value interface{})` - -SetCustom is used to add custom, non-indexed, contextual information to -transactions or errors. If the key contains any special characters -(`.`, `*`, `"`), they will be replaced with underscores. - -Non-indexed means the data is not searchable or aggregatable in Elasticsearch, -and you cannot build dashboards on top of the data. However, non-indexed -information is useful for other reasons, like providing contextual information -to help you quickly debug performance issues or errors. - -The value can be of any type that can be encoded using `encoding/json`. - -TIP: Before using custom context, ensure you understand the different types of -{apm-guide-ref}/data-model-metadata.html[metadata] that are available. - -[float] -[[context-set-username]] -==== `func (*Context) SetUsername(username string)` - -SetUsername records the username of the user associated with the transaction. - -[float] -[[context-set-user-id]] -==== `func (*Context) SetUserID(id string)` - -SetUserID records the ID of the user associated with the transaction. - -[float] -[[context-set-user-email]] -==== `func (*Context) SetUserEmail(email string)` - -SetUserEmail records the email address of the user associated with the transaction. - -// ------------------------------------------------------------------------------------------------- - -[float] -[[error-api]] -=== Errors - -Elastic APM provides two methods of capturing an error event: reporting an error log record, -and reporting an "exception" (either a panic or an error in Go parlance). - -[float] -[[tracer-new-error]] -==== `func (*Tracer) NewError(error) *Error` - -NewError returns a new Error with details taken from err. - -The exception message will be set to `err.Error()`. The exception module and type will be set -to the package and type name of the cause of the error, respectively, where the cause has the -same definition as given by https://github.com/pkg/errors[github.com/pkg/errors]. - -[source,go] ----- -e := apm.DefaultTracer().NewError(err) -... -e.Send() ----- - -The provided error can implement any of several interfaces to provide additional information: - -[source,go] ----- -// Errors implementing ErrorsStacktracer will have their stacktrace -// set based on the result of the StackTrace method. -type ErrorsStacktracer interface { - StackTrace() github.com/pkg/errors.StackTrace -} - -// Errors implementing Stacktracer will have their stacktrace -// set based on the result of the StackTrace method. -type Stacktracer interface { - StackTrace() []go.elastic.co/apm/v2/stacktrace.Frame -} - -// Errors implementing Typer will have a "type" field set to the -// result of the Type method. -type Typer interface { - Type() string -} - -// Errors implementing StringCoder will have a "code" field set to the -// result of the Code method. -type StringCoder interface { - Code() string -} - -// Errors implementing NumberCoder will have a "code" field set to the -// result of the Code method. -type NumberCoder interface { - Code() float64 -} ----- - -Errors created by with NewError will have their ID field populated with a unique ID. -This can be used in your application for correlation. - -[float] -[[tracer-new-error-log]] -==== `func (*Tracer) NewErrorLog(ErrorLogRecord) *Error` - -NewErrorLog returns a new Error for the given ErrorLogRecord: - -[source,go] ----- -type ErrorLogRecord struct { - // Message holds the message for the log record, - // e.g. "failed to connect to %s". - // - // If this is empty, "[EMPTY]" will be used. - Message string - - // MessageFormat holds the non-interpolated format - // of the log record, e.g. "failed to connect to %s". - // - // This is optional. - MessageFormat string - - // Level holds the severity level of the log record. - // - // This is optional. - Level string - - // LoggerName holds the name of the logger used. - // - // This is optional. - LoggerName string - - // Error is an error associated with the log record. - // - // This is optional. - Error error -} ----- - -The resulting Error's log stacktrace will not be set. Call the SetStacktrace method to set it. - -[source,go] ----- -e := apm.DefaultTracer().NewErrorLog(apm.ErrorLogRecord{ - Message: "Somebody set up us the bomb.", -}) -... -e.Send() ----- - -[float] -[[error-set-transaction]] -==== `func (*Error) SetTransaction(*Transaction)` - -SetTransaction associates the error with the given transaction. - -[float] -[[error-set-span]] -==== `func (*Error) SetSpan(*Span)` - -SetSpan associates the error with the given span and the span's transaction. When calling SetSpan, -it is not necessary to also call SetTransaction. - -[float] -[[error-send]] -==== `func (*Error) Send()` - -Send enqueues the error for sending to the Elastic APM server. - -[float] -[[tracer-recovered]] -==== `func (*Tracer) Recovered(interface{}) *Error` - -Recovered returns an Error from the recovered value, optionally associating it with a transaction. -The error is not sent; it is the caller's responsibility to set the error's context, -and then call its `Send` method. - -[source,go] ----- -tx := apm.DefaultTracer().StartTransaction(...) -defer tx.End() -defer func() { - if v := recover(); v != nil { - e := apm.DefaultTracer().Recovered(v) - e.SetTransaction(tx) - e.Send() - } -}() ----- - -[float] -[[apm-captureerror]] -==== `func CaptureError(context.Context, error) *Error` - -CaptureError returns a new error related to the sampled transaction and span present in the context, -if any, and sets its exception details using the given error. The Error.Handled field will be set to -true, and a stacktrace set. - -If there is no transaction in the context, or it is not being sampled, CaptureError returns nil. -As a convenience, if the provided error is nil, then CaptureError will also return nil. - -[source,go] ----- -if err != nil { - e := apm.CaptureError(ctx, err) - e.Send() -} ----- - -[float] -[[trace-context]] -==== Trace Context - -Trace context contains the ID for a transaction or span, the ID of the end-to-end trace to which the -transaction or span belongs, and trace options such as flags relating to sampling. Trace context is -propagated between processes, e.g. in HTTP headers, in order to correlate events originating from -related services. - -Elastic APM's trace context is based on the https://w3c.github.io/trace-context/[W3C Trace Context] draft. - -[float] -[[error-context]] -==== Error Context - -Errors can be associated with context just like transactions. See <> for details. -In addition, errors can be associated with an active transaction or span using -<> or <>, respectively. - -[source,go] ----- -tx := apm.DefaultTracer().StartTransaction("GET /foo", "request") -defer tx.End() -e := apm.DefaultTracer().NewError(err) -e.SetTransaction(tx) -e.Send() ----- - -[float] -[[tracer-config-api]] -==== Tracer Config - -Many configuration attributes can be be updated dynamically via `apm.Tracer` method calls. -Please refer to the documentation at https://pkg.go.dev/go.elastic.co/apm/v2#Tracer[pkg.go.dev/go.elastic.co/apm/v2#Tracer] -for details. The configuration methods are primarily prefixed with `Set`, such as -https://pkg.go.dev/go.elastic.co/apm/v2#Tracer.SetLogger[apm#Tracer.SetLogger]. diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc deleted file mode 100644 index 643c371f8..000000000 --- a/docs/configuration.asciidoc +++ /dev/null @@ -1,758 +0,0 @@ -[[configuration]] -== Configuration - -Adapt the Elastic APM Go agent to your needs with one of the following methods--listed in descending order of precedence: - - 1. {apm-app-ref}/agent-configuration.html[APM Agent Configuration via Kibana] - (supported options are marked with <>) - 2. In code, using the <> - 3. Environment variables - -Configuration defined via Kibana will take precedence over the same -configuration defined in code, which takes precedence over environment -variables. If configuration is defined via Kibana, and then that is -later removed, the agent will revert to configuration defined locally -via either the Tracer Config API or environment variables. - -// tag::setup-config[] -To simplify development and testing, -the agent defaults to sending data to the Elastic APM Server at `http://localhost:8200`. -To send data to an alternative location, you must configure -<>. Depending on the configuration -of your server, you may also need to set <>, -<>, and -<>. All other variables -have usable defaults. -// end::setup-config[] - -[float] -[[dynamic-configuration]] -=== Dynamic configuration - -Configuration options marked with the image:./images/dynamic-config.svg[] badge can be changed at runtime -when set from a supported source. - -The Go Agent supports {apm-app-ref}/agent-configuration.html[Central configuration], -which allows you to fine-tune certain configurations via the APM app. -This feature is enabled in the Agent by default, with <>. - -[float] -=== Configuration formats - -Some options require a unit, either duration or size. These need to be provided -in a specific format. - -[float] -==== Duration format - -The _duration_ format is used for options like timeouts. The unit is provided as -a suffix directly after the number, without any whitespace. - -*Example:* `5ms` - -*Supported units:* - -- `ms` (milliseconds) -- `s` (seconds) -- `m` (minutes) - -[float] -==== Size format - -The _size_ format is used for options such as maximum buffer sizes. The unit is -provided as a suffix directly after the number, without any whitespace. - -*Example:* `10KB` - -*Supported units:* - -- B (bytes) -- KB (kilobytes) -- MB (megabytes) -- GB (gigabytes) - -NOTE: We use the power-of-two sizing convention, e.g. 1KB = 1024B. - -[float] -[[config-server-url]] -=== `ELASTIC_APM_SERVER_URL` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SERVER_URL` | `http://localhost:8200` | `http://localhost:8200` -|============ - -The URL for your Elastic APM Server. The Server supports both HTTP and HTTPS. -If you use HTTPS, then you may need to configure your client machines so -that the server certificate can be verified. You can disable certificate -verification with <>. - -[float] -[[config-server-timeout]] -=== `ELASTIC_APM_SERVER_TIMEOUT` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SERVER_TIMEOUT` | `30s` | `30s` -|============ - -The timeout for requests made to your Elastic APM server. When set to zero -or a negative value, timeouts will be disabled. - -[float] -[[config-secret-token]] -=== `ELASTIC_APM_SECRET_TOKEN` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SECRET_TOKEN` | | "A random string" -|============ - -This string is used to ensure that only your agents can send data to your APM server. -Both the agents and the APM server have to be configured with the same secret token. - -WARNING: The secret token is sent as plain-text in every request to the server, so you -should also secure your communications using HTTPS. Unless you do so, your secret token -could be observed by an attacker. - -[float] -[[config-api-key]] -=== `ELASTIC_APM_API_KEY` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_API_KEY` | | "A base64-encoded string" -|============ - -This base64-encoded string is used to ensure that only your agents can send data to your APM server. -The API key must be created using the APM Server {apm-guide-ref}/api-key.html[command line tool]. - -WARNING: The API Key is sent as plain-text in every request to the server, so you should also secure -your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. - -[float] -[[config-service-name]] -=== `ELASTIC_APM_SERVICE_NAME` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SERVICE_NAME` | Executable name | `my-app` -|============ - -The name of your service or application. This is used to keep all the errors and -transactions of your service together and is the primary filter in the Elastic APM -user interface. - -If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the -executable name. e.g. if your executable is called "my-app.exe", then your -service will be identified as "my-app". - -NOTE: The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. -In other words: your service name must only contain characters from the ASCII -alphabet, numbers, dashes, underscores, and spaces. - -[float] -[[config-service-version]] -=== `ELASTIC_APM_SERVICE_VERSION` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SERVICE_VERSION` | | A string indicating the version of the deployed service -|============ - -A version string for the currently deployed version of the service. -If you don't version your deployments, the recommended value for this field is the commit identifier -of the deployed revision, e.g. the output of `git rev-parse HEAD`. - -[float] -[[config-service-node-name]] -=== `ELASTIC_APM_SERVICE_NODE_NAME` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SERVICE_NODE_NAME` | | `my-node-name` -|============ - -Optional name used to differentiate between nodes in a service. -Must be unique, otherwise data from multiple nodes will be aggregated together. - -If you do not specify `ELASTIC_APM_SERVICE_NODE_NAME`, service nodes will be identified using the container ID if available, -otherwise the host name. - -NOTE: This feature is fully supported in the APM Server versions >= 7.5. - -[float] -[[config-environment]] -=== `ELASTIC_APM_ENVIRONMENT` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_ENVIRONMENT` | | `"production"` -|============ - -The name of the environment this service is deployed in, e.g. "production" or "staging". - -Environments allow you to easily filter data on a global level in the APM app. -It's important to be consistent when naming environments across agents. -See {apm-app-ref}/filters.html#environment-selector[environment selector] in the APM app for more information. - -NOTE: This feature is fully supported in the APM app in Kibana versions >= 7.2. -You must use the query bar to filter for a specific environment in versions prior to 7.2. - -[float] -[[config-active]] -=== `ELASTIC_APM_ACTIVE` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_ACTIVE` | true | `false` -|============ - -Enable or disable the agent. If set to false, then the Go agent does not send -any data to the Elastic APM server, and instrumentation overhead is minimized. - -[float] -[[config-recording]] -=== `ELASTIC_APM_RECORDING` - -<> - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_RECORDING` | true | `false` -|============ - -Enable or disable recording of events. If set to false, then the Go agent does not -send any events to the Elastic APM server, and instrumentation overhead is -minimized, but the agent will continue to poll the server for configuration changes. - -[float] -[[config-global-labels]] -=== `ELASTIC_APM_GLOBAL_LABELS` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_GLOBAL_LABELS` | | `dept=engineering,rack=number8` -|============ - -Labels are added to all events. The format for labels is: `key=value[,key=value[,...]]`. -Any labels set by application via the API will override global labels with the same keys. - -This option requires APM Server 7.2 or greater, and will have no effect when using older -server versions. - -[float] -[[config-ignore-urls]] -=== `ELASTIC_APM_TRANSACTION_IGNORE_URLS` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | | `/heartbeat*, *.jpg` -|============ - -A list of patterns to match HTTP requests to ignore. An incoming HTTP request -whose request line matches any of the patterns will not be reported as a transaction. - -This option supports the wildcard `*`, which matches zero or more characters. -Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. -Prefixing a pattern with `(?-i)` makes the matching case sensitive. - -NOTE: This configuration was previously known as `ELASTIC_APM_IGNORE_URLS`, which has been deprecated and will be removed in a future major -version of the agent. - -[float] -[[config-sanitize-field-names]] -=== `ELASTIC_APM_SANITIZE_FIELD_NAMES` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `password, passwd, pwd, secret, *key, *token*, *session*, *credit*, *card*, *auth*, set-cookie, *principal*` | `sekrits` -|============ - -A list of patterns to match the names of HTTP headers, cookies, and POST form fields to redact. - -This option supports the wildcard `*`, which matches zero or more characters. -Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. -Prefixing a pattern with `(?-i)` makes the matching case sensitive. - -[float] -[[config-capture-headers]] -=== `ELASTIC_APM_CAPTURE_HEADERS` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_CAPTURE_HEADERS` | `true` -|============ - -For transactions that are HTTP requests, the Go agent can optionally capture request and response headers. - -Possible values: `true`, `false`. - -Captured headers are subject to sanitization, per <>. - -[float] -[[config-capture-body]] -=== `ELASTIC_APM_CAPTURE_BODY` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_CAPTURE_BODY` | `off` -|============ - -For transactions that are HTTP requests, the Go agent can optionally capture the request body. - -Possible values: `errors`, `transactions`, `all`, `off`. - -WARNING: Request bodies often contain sensitive values like passwords, credit card numbers, and so on. -If your service handles data like this, enable this feature with care. - -[float] -[[config-hostname]] -=== `ELASTIC_APM_HOSTNAME` - -[options="header"] -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_HOSTNAME` | `os.Hostname()` | `app-server01` -|============ - -The host name to use when sending error and transaction data to the APM server. - -[float] -[[config-api-request-time]] -=== `ELASTIC_APM_API_REQUEST_TIME` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_API_REQUEST_TIME` | `10s` -|============ - -The amount of time to wait before ending a request to the Elastic APM server. -When you report transactions, spans and errors, the agent will initiate a -request and send them to the server when there is enough data to send; the -request will remain open until this time has been exceeded, or until the -<> has been reached. - -[float] -[[config-api-request-size]] -=== `ELASTIC_APM_API_REQUEST_SIZE` - -[options="header"] -|============ -| Environment | Default | Minimum | Maximum -| `ELASTIC_APM_API_REQUEST_SIZE` | `750KB` | `1KB` | `5MB` -|============ - -The maximum size of request bodies to send to the Elastic APM server. -The agent will maintain an in-memory buffer of compressed data for streaming -to the APM server. - -[float] -[[config-api-buffer-size]] -=== `ELASTIC_APM_API_BUFFER_SIZE` - -[options="header"] -|============ -| Environment | Default | Minimum | Maximum -| `ELASTIC_APM_API_BUFFER_SIZE` | `1MB` | `10KB` | `100MB` -|============ - -The maximum number of bytes of uncompressed, encoded events to store in memory -while the agent is busy. When the agent is able to, it will transfer buffered -data to the request buffer, and start streaming it to the server. If the buffer -fills up, new events will start replacing older ones. - -[float] -[[config-transaction-max-spans]] -=== `ELASTIC_APM_TRANSACTION_MAX_SPANS` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `500` -|============ - -Limits the amount of spans that are recorded per transaction. - -This is helpful in cases where a transaction creates a large number -of spans (e.g. thousands of SQL queries). Setting an upper limit will -prevent overloading the agent and the APM server with too much work -for such edge cases. - -[float] -[[config-exit-span-min-duration]] -=== `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` | `1ms` -|============ - -Sets the minimum duration for an exit span to be reported. Spans shorter or -equal to this threshold will be dropped by the agent and reported as statistics -in the span's transaction, as long as the transaction didn't end before the span -was reported. - -When span compression is enabled (<>), the sum -of the compressed span composite is considered. - -The minimum duration allowed for this setting is 1 microsecond (`us`). - -[float] -[[config-span-frames-min-duration-ms]] -=== `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `5ms` -|============ - -The APM agent will collect a stack trace for every recorded span whose duration -exceeds this configured value. While this is very helpful to find the exact -place in your code that causes the span, collecting this stack trace does have -some processing and storage overhead. - -NOTE: This configuration has been deprecated and will be removed in a future major version of the agent. - -[float] -[[config-span-stack-trace-min-duration]] -=== `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `5ms` -|============ - -The APM agent will collect a stack trace for every recorded span whose duration -exceeds this configured value. While this is very helpful to find the exact -place in your code that causes the span, collecting this stack trace does have -some processing and storage overhead. - -NOTE: This configuration was previously known as `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION`, which has been deprecated and will be removed in a future major -version of the agent. - -[float] -[[config-stack-trace-limit]] -=== `ELASTIC_APM_STACK_TRACE_LIMIT` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_STACK_TRACE_LIMIT` | `50` -|============ - -Limits the number of frames captured for each stack trace. - -Setting the limit to 0 will disable stack trace collection, while any positive -integer value will be used as the maximum number of frames to collect. Setting -a negative value, such as -1, means that all frames will be collected. - -[float] -[[config-transaction-sample-rate]] -=== `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `1.0` -|============ - -By default, the agent will sample every transaction (e.g. request to your service). -To reduce overhead and storage requirements, set the sample rate to a value -between `0.0` and `1.0`. We still record overall time and the result for unsampled -transactions, but no context information, tags, or spans. - -[float] -[[config-metrics-interval]] -=== `ELASTIC_APM_METRICS_INTERVAL` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_METRICS_INTERVAL` | 30s -|============ - -The interval at which APM agent gathers and reports metrics. Set to `0s` to disable. - -[float] -[[config-disable-metrics]] -=== `ELASTIC_APM_DISABLE_METRICS` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_DISABLE_METRICS` | | `system.*, *cpu*` -|============ - -Disables the collection of certain metrics. If the name of a metric matches any of -the wildcard expressions, it will not be collected. - -This option supports the wildcard `*`, which matches zero or more characters. -Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. -Prefixing a pattern with `(?-i)` makes the matching case sensitive. - -[float] -[[config-breakdown-metrics]] -=== `ELASTIC_APM_BREAKDOWN_METRICS` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_BREAKDOWN_METRICS` | `true` -|============ - -Capture breakdown metrics. Set to `false` to disable. - -[float] -[[config-server-cert]] -=== `ELASTIC_APM_SERVER_CERT` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SERVER_CERT` | -|============ - -If you have configured your APM Server with a self signed TLS certificate, or you -want to pin the server certificate, specify the path to the PEM-encoded -certificate via the `ELASTIC_APM_SERVER_CERT` configuration. - -[float] -[[config-server-ca-cert-file]] -=== `ELASTIC_APM_SERVER_CA_CERT_FILE` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SERVER_CA_CERT_FILE` | -|============ - -The path to a PEM-encoded TLS Certificate Authority certificate that will be -used for verifying the server's TLS certificate chain. - -[float] -[[config-verify-server-cert]] -=== `ELASTIC_APM_VERIFY_SERVER_CERT` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_VERIFY_SERVER_CERT` | `true` -|============ - -By default, the agent verifies the server's certificate if you use an -HTTPS connection to the APM server. Verification can be disabled by -changing this setting to `false`. This setting is ignored when -`ELASTIC_APM_SERVER_CERT` is set. - -[float] -[[config-log-file]] -=== `ELASTIC_APM_LOG_FILE` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_LOG_FILE` | -|============ - -`ELASTIC_APM_LOG_FILE` specifies the output file for the agent's default, internal -logger. The file will be created, or truncated if it exists, when the process starts. -By default, logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable -it. This environment variable will be ignored if a logger is configured programatically. - -There are two special file names that the agent recognizes: `stdout` and `stderr`. -These will configure the logger to write to standard output and standard error -respectively. - -[float] -[[config-log-level]] -=== `ELASTIC_APM_LOG_LEVEL` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_LOG_LEVEL` | `"error"` -|============ - -`ELASTIC_APM_LOG_LEVEL` specifies the log level for the agent's default, internal -logger. The only two levels used by the logger are "error" and "debug". By default, -logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable it. - -This environment variable will be ignored if a logger is configured programatically. - -[float] -[[config-central-config]] -==== `ELASTIC_APM_CENTRAL_CONFIG` - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_CENTRAL_CONFIG` | `true` -|============ - -Activate APM Agent central configuration via Kibana. By default the agent will poll the server -for agent configuration changes. This can be disabled by changing the setting to `false`. -See {kibana-ref}/agent-configuration.html[APM Agent central configuration] for more information. - -NOTE: This feature requires APM Server v7.3 or later. - -[float] -[[config-use-elastic-traceparent-header]] -==== `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` -|============ -| Environment | Default -| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `true` -|============ - -To enable {apm-guide-ref}/apm-distributed-tracing.html[distributed tracing], the agent -adds trace context headers to outgoing HTTP requests made with <>. -These headers (`traceparent` and `tracestate`) are defined in the -https://www.w3.org/TR/trace-context-1/[W3C Trace Context] specification. - -When this setting is `true`, the agent will also add the header `elastic-apm-traceparent` -for backwards compatibility with older versions of Elastic APM agents. - -[float] -[[config-cloud-provider]] -==== `ELASTIC_APM_CLOUD_PROVIDER` - -[options="header"] -|============ -| Environment | Default | Example -| `ELASTIC_APM_CLOUD_PROVIDER` | `"auto"` | `"aws"` -|============ - -This config value allows you to specify which cloud provider should be assumed -for metadata collection. By default, the agent will use trial and error to -automatically collect the cloud metadata. - -Valid options are `"none"`, `"auto"`, `"aws"`, `"gcp"`, and `"azure"` -If this config value is set to `"none"`, then no cloud metadata will be collected. - -[float] -[[config-span-compression-enabled]] -=== `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `true` -|============ - -When enabled, the agent will attempt to compress _short_ exit spans that share the -same parent into a composite span. The exact duration for what is considered -_short_, depends on the compression strategy used (`same_kind` or `exact_match`). - -In order for a span to be compressible, these conditions need to be met: - -* Spans are exit spans. -* Spans are siblings (share the same parent). -* Spans have not propagated their context downstream. -* Each span duration is equal or lower to the compression strategy maximum duration. -* Spans are compressed with `same_kind` strategy when these attributes are equal: -** `span.type`. -** `span.subtype`. -** `span.context.destination.service.resource` -* Spans are compressed with `exact_match` strategy when all the previous conditions -are met and the `span.name` is equal. - -Compressing short exit spans should provide some storage savings for services that -create a lot of consecutive short exit spans to for example databases or cache -services which are generally uninteresting when viewing a trace. - -experimental::["This feature is experimental and requires APM Server v7.15 or later."] - -[float] -[[config-span-compression-exact-match-duration]] -=== `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `50ms` -|============ - -The maximum duration to consider for compressing sibling exit spans that are an -exact match for compression. - -[float] -[[config-span-compression-same-kind-duration]] -=== `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `0ms` -|============ - -The maximum duration to consider for compressing sibling exit spans that are of -the same kind for compression. - -[float] -[[config-trace-continuation-strategy]] -=== `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` - -<> - -[options="header"] -|============ -| Environment | Default -| `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` | `continue` -|============ - -This option allows some control over how the APM agent handles W3C trace-context headers on incoming requests. -By default, the traceparent and tracestate headers are used per W3C spec for distributed tracing. -However, in certain cases it can be helpful to not use the incoming traceparent header. Some example use cases: - -- An Elastic-monitored service is receiving requests with traceparent headers from unmonitored services. -- An Elastic-monitored service is publicly exposed, and does not want tracing data (trace-ids, sampling decisions) to possibly be spoofed by user requests. - -Valid options are `continue`, `restart`, and `restart_external`: - -continue:: The default behavior. An incoming `traceparent` value is used to continue the trace and determine the sampling decision. -restart:: Always ignores the `traceparent` header of incoming requests. A new trace-id will be generated and the sampling decision will be made based on `transaction_sample_rate`. A span link will be made to the incoming `traceparent`. -restart_external:: If an incoming request includes the `es` vendor flag in `tracestate`, then any `traceparent` will be considered internal and will be handled as described for *continue* above. Otherwise, any `traceparent` is considered external and will be handled as described for *restart* above. - -Starting with Elastic Observability 8.2, span links are visible in trace views. diff --git a/docs/context-propagation.asciidoc b/docs/context-propagation.asciidoc deleted file mode 100644 index 62ff4b27f..000000000 --- a/docs/context-propagation.asciidoc +++ /dev/null @@ -1,103 +0,0 @@ -[[custom-instrumentation-propagation]] -=== Context propagation - -In Go, https://golang.org/pkg/context/[context] is used to propagate request-scoped values along a call -chain, potentially crossing between goroutines and between processes. For servers based on `net/http`, -each request contains an independent context object, which allows adding values specific to that particular -request. - -When you start a transaction, you can add it to a context object using -<>. This context object can be -later passed to <> to obtain -the transaction, or into <> to start a span. - -The simplest way to create and propagate a span is by using <>, -which takes a context and returns a span. The span will be created as a child of the span most recently -added to this context, or a transaction added to the context as described above. If the context contains -neither a transaction nor a span, then the span will be dropped (i.e. will not be reported to the APM Server.) - -For example, take a simple CRUD-type web service, which accepts requests over HTTP and then makes -corresponding database queries. For each incoming request, a transaction will be started and added to the -request context automatically. This context needs to be passed into method calls within the handler manually -in order to create spans within that transaction, e.g. to measure the duration of SQL queries. - -[source,go] ----- -import ( - "net/http" - - "go.elastic.co/apm/v2" - "go.elastic.co/apm/module/apmhttp/v2" - "go.elastic.co/apm/module/apmsql/v2" - _ "go.elastic.co/apm/module/apmsql/v2/pq" -) - -var db *sql.DB - -func init() { - // apmsql.Open wraps sql.Open, in order - // to add tracing to database operations. - db, _ = apmsql.Open("postgres", "") -} - -func main() { - mux := http.NewServeMux() - mux.HandleFunc("/", handleList) - - // apmhttp.Wrap instruments an http.Handler, in order - // to report any request to this handler as a transaction, - // and to store the transaction in the request's context. - handler := apmhttp.Wrap(mux) - http.ListenAndServe(":8080", handler) -} - -func handleList(w http.ResponseWriter, req *http.Request) { - // By passing the request context down to getList, getList can add spans to it. - ctx := req.Context() - getList(ctx) - ... -} - -func getList(ctx context.Context) ( - // When getList is called with a context containing a transaction or span, - // StartSpan creates a child span. In this example, getList is always called - // with a context containing a transaction for the handler, so we should - // expect to see something like: - // - // Transaction: handleList - // Span: getList - // Span: SELECT FROM items - // - span, ctx := apm.StartSpan(ctx, "getList", "custom") - defer span.End() - - // NOTE: The context object ctx returned by StartSpan above contains - // the current span now, so subsequent calls to StartSpan create new - // child spans. - - // db was opened with apmsql, so queries will be reported as - // spans when using the context methods. - rows, err := db.QueryContext(ctx, "SELECT * FROM items") - ... - rows.Close() -} ----- - -Contexts can have deadlines associated and can be explicitly canceled. In some cases you may -wish to propagate the trace context (parent transaction/span) to some code without propagating -the cancellation. For example, an HTTP request's context will be canceled when the client's -connection closes. You may want to perform some operation in the request handler without it -being canceled due to the client connection closing, such as in a fire-and-forget operation. -To handle scenarios like this, we provide the function <>. - -[source,go] ----- -func handleRequest(w http.ResponseWriter, req *http.Request) { - go fireAndForget(apm.DetachedContext(req.Context())) - - // After handleRequest returns, req.Context() will be canceled, - // but the "detached context" passed into fireAndForget will not. - // Any spans created by fireAndForget will still be joined to - // the handleRequest transaction. -} ----- diff --git a/docs/contributing.asciidoc b/docs/contributing.asciidoc deleted file mode 100644 index 2fbbe4e6a..000000000 --- a/docs/contributing.asciidoc +++ /dev/null @@ -1,16 +0,0 @@ -[[contributing]] -== Contributing - -The Go APM Agent is open source and we love to receive contributions from our community — you! - -There are many ways to contribute, from writing tutorials or blog posts, improving the -documentation, submitting bug reports and feature requests or writing code. - -You can get in touch with us through {apm-forum}[Discuss]. -Feedback and ideas are always welcome. - -[float] -=== Reporting bugs and contributing code - -To report bugs, please create an Issue on the https://github.com/elastic/apm-agent-go[apm-agent-go] GitHub repository. For tips on contributing code fixes or enhancements, please see the https://github.com/elastic/apm-agent-go/blob/main/CONTRIBUTING.md[contributing guide] in the code repository. - diff --git a/docs/custom-instrumentation.asciidoc b/docs/custom-instrumentation.asciidoc deleted file mode 100644 index d4d2e905b..000000000 --- a/docs/custom-instrumentation.asciidoc +++ /dev/null @@ -1,90 +0,0 @@ -[[custom-instrumentation]] -=== Custom instrumentation - -To report on the performance of transactions served by your application, use the Go -agent's <>. Instrumentation refers to modifying your application code to report a: - - - <> - A top-level operation in your application, -such as an HTTP or RPC request. - - <> - An operation within a transaction, -such as a database query, or a request to another service. - - <> - May refer to Go errors or panics. - -To report these, use a <> -- typically -`apm.DefaultTracer()`, which is configured via environment variables. In the code -examples below, we will refer to `apm.DefaultTracer()`. Please refer to the <> -for a more thorough description of the types and methods. - -[[custom-instrumentation-transactions]] -==== Transactions - -To report a transaction, call <> -with the transaction name and type. This returns a `Transaction` object; the transaction -can be customized with additional context before you call its `End` method to indicate -that the transaction has completed. Once the transaction's `End` method is called, it -will be enqueued for sending to the Elastic APM server, and made available to the APM app. - -[source,go] ----- -tx := apm.DefaultTracer().StartTransaction("GET /api/v1", "request") -defer tx.End() -... -tx.Result = "HTTP 2xx" -tx.Context.SetLabel("region", "us-east-1") ----- - -The agent supports sampling transactions: non-sampled transactions will be still be -reported, but with limited context and without any spans. To determine whether a -transaction is sampled, use the `Transaction.Sampled` method; if it returns false, -you should avoid unnecessary storage or processing required for setting transaction -context. - -Once you have started a transaction, you can include it in a `context` object for -propagating throughout the application. See <> -for more details. - -[source,go] ----- -ctx = apm.ContextWithTransaction(ctx, tx) ----- - -[[custom-instrumentation-spans]] -==== Spans - -To report an operation within a transaction, use <> -or <> to start a span given a transaction or a `context` -containing a transaction, respectively. Like a transaction, a span has a name and a type. A span can have a parent span within the same transaction. If the context provided to `apm.StartSpan` -contains a span, then that will be considered the parent. See <> -for more details. - -[source,go] ----- -span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query") -defer span.End() ----- - -`Transaction.StartSpan` and `apm.StartSpan` will always return a non-nil `Span`, even if the -transaction is nil. It is always safe to defer a call to the span's End method. If setting the span's -context would incur significant overhead, you may want to check if the span is dropped first, by calling -the `Span.Dropped` method. - -[[custom-instrumentation-errors]] -==== Panic recovery and errors - -To recover panics and report them along with your transaction, use the -<> method in a recovery function. There are also methods for reporting -non-panic errors: <>, <>, and -<>. - -[source,go] ----- -defer func() { - if v := recover(); v != nil { - e := apm.DefaultTracer().Recovered() - e.SetTransaction(tx) // or e.SetSpan(span) - e.Send() - } -}() ----- - -See the <> for details and examples of the other methods. diff --git a/docs/docset.yml b/docs/docset.yml new file mode 100644 index 000000000..c490ae1cf --- /dev/null +++ b/docs/docset.yml @@ -0,0 +1,493 @@ +project: 'APM Go agent docs' +cross_links: + - apm-agent-rum-js + - beats + - docs-content + - ecs + - ecs-logging + - ecs-logging-go-logrus + - ecs-logging-go-zap + - elasticsearch +toc: + - toc: reference + - toc: release-notes +subs: + ref: "https://www.elastic.co/guide/en/elasticsearch/reference/current" + ref-bare: "https://www.elastic.co/guide/en/elasticsearch/reference" + ref-8x: "https://www.elastic.co/guide/en/elasticsearch/reference/8.1" + ref-80: "https://www.elastic.co/guide/en/elasticsearch/reference/8.0" + ref-7x: "https://www.elastic.co/guide/en/elasticsearch/reference/7.17" + ref-70: "https://www.elastic.co/guide/en/elasticsearch/reference/7.0" + ref-60: "https://www.elastic.co/guide/en/elasticsearch/reference/6.0" + ref-64: "https://www.elastic.co/guide/en/elasticsearch/reference/6.4" + xpack-ref: "https://www.elastic.co/guide/en/x-pack/6.2" + logstash-ref: "https://www.elastic.co/guide/en/logstash/current" + kibana-ref: "https://www.elastic.co/guide/en/kibana/current" + kibana-ref-all: "https://www.elastic.co/guide/en/kibana" + beats-ref-root: "https://www.elastic.co/guide/en/beats" + beats-ref: "https://www.elastic.co/guide/en/beats/libbeat/current" + beats-ref-60: "https://www.elastic.co/guide/en/beats/libbeat/6.0" + beats-ref-63: "https://www.elastic.co/guide/en/beats/libbeat/6.3" + beats-devguide: "https://www.elastic.co/guide/en/beats/devguide/current" + auditbeat-ref: "https://www.elastic.co/guide/en/beats/auditbeat/current" + packetbeat-ref: "https://www.elastic.co/guide/en/beats/packetbeat/current" + metricbeat-ref: "https://www.elastic.co/guide/en/beats/metricbeat/current" + filebeat-ref: "https://www.elastic.co/guide/en/beats/filebeat/current" + functionbeat-ref: "https://www.elastic.co/guide/en/beats/functionbeat/current" + winlogbeat-ref: "https://www.elastic.co/guide/en/beats/winlogbeat/current" + heartbeat-ref: "https://www.elastic.co/guide/en/beats/heartbeat/current" + journalbeat-ref: "https://www.elastic.co/guide/en/beats/journalbeat/current" + ingest-guide: "https://www.elastic.co/guide/en/ingest/current" + fleet-guide: "https://www.elastic.co/guide/en/fleet/current" + apm-guide-ref: "https://www.elastic.co/guide/en/apm/guide/current" + apm-guide-7x: "https://www.elastic.co/guide/en/apm/guide/7.17" + apm-app-ref: "https://www.elastic.co/guide/en/kibana/current" + apm-agents-ref: "https://www.elastic.co/guide/en/apm/agent" + apm-android-ref: "https://www.elastic.co/guide/en/apm/agent/android/current" + apm-py-ref: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-py-ref-3x: "https://www.elastic.co/guide/en/apm/agent/python/3.x" + apm-node-ref-index: "https://www.elastic.co/guide/en/apm/agent/nodejs" + apm-node-ref: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-node-ref-1x: "https://www.elastic.co/guide/en/apm/agent/nodejs/1.x" + apm-rum-ref: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-dotnet-ref: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref: "https://www.elastic.co/guide/en/apm/agent/php/current" + apm-ios-ref: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-lambda-ref: "https://www.elastic.co/guide/en/apm/lambda/current" + apm-attacher-ref: "https://www.elastic.co/guide/en/apm/attacher/current" + docker-logging-ref: "https://www.elastic.co/guide/en/beats/loggingplugin/current" + esf-ref: "https://www.elastic.co/guide/en/esf/current" + kinesis-firehose-ref: "https://www.elastic.co/guide/en/kinesis/{{kinesis_version}}" + estc-welcome-current: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current" + estc-welcome-all: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions" + hadoop-ref: "https://www.elastic.co/guide/en/elasticsearch/hadoop/current" + stack-ref: "https://www.elastic.co/guide/en/elastic-stack/current" + stack-ref-67: "https://www.elastic.co/guide/en/elastic-stack/6.7" + stack-ref-68: "https://www.elastic.co/guide/en/elastic-stack/6.8" + stack-ref-70: "https://www.elastic.co/guide/en/elastic-stack/7.0" + stack-ref-80: "https://www.elastic.co/guide/en/elastic-stack/8.0" + stack-ov: "https://www.elastic.co/guide/en/elastic-stack-overview/current" + stack-gs: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + stack-gs-current: "https://www.elastic.co/guide/en/elastic-stack-get-started/current" + javaclient: "https://www.elastic.co/guide/en/elasticsearch/client/java-api/current" + java-api-client: "https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current" + java-rest: "https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current" + jsclient: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + jsclient-current: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current" + es-ruby-client: "https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current" + es-dotnet-client: "https://www.elastic.co/guide/en/elasticsearch/client/net-api/current" + es-php-client: "https://www.elastic.co/guide/en/elasticsearch/client/php-api/current" + es-python-client: "https://www.elastic.co/guide/en/elasticsearch/client/python-api/current" + defguide: "https://www.elastic.co/guide/en/elasticsearch/guide/2.x" + painless: "https://www.elastic.co/guide/en/elasticsearch/painless/current" + plugins: "https://www.elastic.co/guide/en/elasticsearch/plugins/current" + plugins-8x: "https://www.elastic.co/guide/en/elasticsearch/plugins/8.1" + plugins-7x: "https://www.elastic.co/guide/en/elasticsearch/plugins/7.17" + plugins-6x: "https://www.elastic.co/guide/en/elasticsearch/plugins/6.8" + glossary: "https://www.elastic.co/guide/en/elastic-stack-glossary/current" + upgrade_guide: "https://www.elastic.co/products/upgrade_guide" + blog-ref: "https://www.elastic.co/blog/" + curator-ref: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + curator-ref-current: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current" + metrics-ref: "https://www.elastic.co/guide/en/metrics/current" + metrics-guide: "https://www.elastic.co/guide/en/metrics/guide/current" + logs-ref: "https://www.elastic.co/guide/en/logs/current" + logs-guide: "https://www.elastic.co/guide/en/logs/guide/current" + uptime-guide: "https://www.elastic.co/guide/en/uptime/current" + observability-guide: "https://www.elastic.co/guide/en/observability/current" + observability-guide-all: "https://www.elastic.co/guide/en/observability" + siem-guide: "https://www.elastic.co/guide/en/siem/guide/current" + security-guide: "https://www.elastic.co/guide/en/security/current" + security-guide-all: "https://www.elastic.co/guide/en/security" + endpoint-guide: "https://www.elastic.co/guide/en/endpoint/current" + sql-odbc: "https://www.elastic.co/guide/en/elasticsearch/sql-odbc/current" + ecs-ref: "https://www.elastic.co/guide/en/ecs/current" + ecs-logging-ref: "https://www.elastic.co/guide/en/ecs-logging/overview/current" + ecs-logging-go-logrus-ref: "https://www.elastic.co/guide/en/ecs-logging/go-logrus/current" + ecs-logging-go-zap-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-go-zerolog-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current" + ecs-logging-java-ref: "https://www.elastic.co/guide/en/ecs-logging/java/current" + ecs-logging-dotnet-ref: "https://www.elastic.co/guide/en/ecs-logging/dotnet/current" + ecs-logging-nodejs-ref: "https://www.elastic.co/guide/en/ecs-logging/nodejs/current" + ecs-logging-php-ref: "https://www.elastic.co/guide/en/ecs-logging/php/current" + ecs-logging-python-ref: "https://www.elastic.co/guide/en/ecs-logging/python/current" + ecs-logging-ruby-ref: "https://www.elastic.co/guide/en/ecs-logging/ruby/current" + ml-docs: "https://www.elastic.co/guide/en/machine-learning/current" + eland-docs: "https://www.elastic.co/guide/en/elasticsearch/client/eland/current" + eql-ref: "https://eql.readthedocs.io/en/latest/query-guide" + extendtrial: "https://www.elastic.co/trialextension" + wikipedia: "https://en.wikipedia.org/wiki" + forum: "https://discuss.elastic.co/" + xpack-forum: "https://discuss.elastic.co/c/50-x-pack" + security-forum: "https://discuss.elastic.co/c/x-pack/shield" + watcher-forum: "https://discuss.elastic.co/c/x-pack/watcher" + monitoring-forum: "https://discuss.elastic.co/c/x-pack/marvel" + graph-forum: "https://discuss.elastic.co/c/x-pack/graph" + apm-forum: "https://discuss.elastic.co/c/apm" + enterprise-search-ref: "https://www.elastic.co/guide/en/enterprise-search/current" + app-search-ref: "https://www.elastic.co/guide/en/app-search/current" + workplace-search-ref: "https://www.elastic.co/guide/en/workplace-search/current" + enterprise-search-node-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/enterprise-search-node/current" + enterprise-search-php-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/php/current" + enterprise-search-python-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/python/current" + enterprise-search-ruby-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current" + elastic-maps-service: "https://maps.elastic.co" + integrations-docs: "https://docs.elastic.co/en/integrations" + integrations-devguide: "https://www.elastic.co/guide/en/integrations-developer/current" + time-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units" + byte-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units" + apm-py-ref-v: "https://www.elastic.co/guide/en/apm/agent/python/current" + apm-node-ref-v: "https://www.elastic.co/guide/en/apm/agent/nodejs/current" + apm-rum-ref-v: "https://www.elastic.co/guide/en/apm/agent/rum-js/current" + apm-ruby-ref-v: "https://www.elastic.co/guide/en/apm/agent/ruby/current" + apm-java-ref-v: "https://www.elastic.co/guide/en/apm/agent/java/current" + apm-go-ref-v: "https://www.elastic.co/guide/en/apm/agent/go/current" + apm-ios-ref-v: "https://www.elastic.co/guide/en/apm/agent/swift/current" + apm-dotnet-ref-v: "https://www.elastic.co/guide/en/apm/agent/dotnet/current" + apm-php-ref-v: "https://www.elastic.co/guide/en/apm/agent/php/current" + ecloud: "Elastic Cloud" + esf: "Elastic Serverless Forwarder" + ess: "Elasticsearch Service" + ece: "Elastic Cloud Enterprise" + eck: "Elastic Cloud on Kubernetes" + serverless-full: "Elastic Cloud Serverless" + serverless-short: "Serverless" + es-serverless: "Elasticsearch Serverless" + es3: "Elasticsearch Serverless" + obs-serverless: "Elastic Observability Serverless" + sec-serverless: "Elastic Security Serverless" + serverless-docs: "https://docs.elastic.co/serverless" + cloud: "https://www.elastic.co/guide/en/cloud/current" + ess-utm-params: "?page=docs&placement=docs-body" + ess-baymax: "?page=docs&placement=docs-body" + ess-trial: "https://cloud.elastic.co/registration?page=docs&placement=docs-body" + ess-product: "https://www.elastic.co/cloud/elasticsearch-service?page=docs&placement=docs-body" + ess-console: "https://cloud.elastic.co?page=docs&placement=docs-body" + ess-console-name: "Elasticsearch Service Console" + ess-deployments: "https://cloud.elastic.co/deployments?page=docs&placement=docs-body" + ece-ref: "https://www.elastic.co/guide/en/cloud-enterprise/current" + eck-ref: "https://www.elastic.co/guide/en/cloud-on-k8s/current" + ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. https://cloud.elastic.co/registration{ess-utm-params}[Try the Elasticsearch Service for free]." + ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can https://cloud.elastic.co/registration{ess-utm-params}[try it for free]." + ess-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elasticsearch Service\"]" + ece-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud_ece.svg[link=\"https://cloud.elastic.co/registration{ess-utm-params}\", title=\"Supported on Elastic Cloud Enterprise\"]" + cloud-only: "This feature is designed for indirect use by https://cloud.elastic.co/registration{ess-utm-params}[Elasticsearch Service], https://www.elastic.co/guide/en/cloud-enterprise/{ece-version-link}[Elastic Cloud Enterprise], and https://www.elastic.co/guide/en/cloud-on-k8s/current[Elastic Cloud on Kubernetes]. Direct use is not supported." + ess-setting-change: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"{ess-trial}\", title=\"Supported on {ess}\"] indicates a change to a supported https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html[user setting] for Elasticsearch Service." + ess-skip-section: "If you use Elasticsearch Service, skip this section. Elasticsearch Service handles these changes for you." + api-cloud: "https://www.elastic.co/docs/api/doc/cloud" + api-ece: "https://www.elastic.co/docs/api/doc/cloud-enterprise" + api-kibana-serverless: "https://www.elastic.co/docs/api/doc/serverless" + es-feature-flag: "This feature is in development and not yet available for use. This documentation is provided for informational purposes only." + es-ref-dir: "'{{elasticsearch-root}}/docs/reference'" + apm-app: "APM app" + uptime-app: "Uptime app" + synthetics-app: "Synthetics app" + logs-app: "Logs app" + metrics-app: "Metrics app" + infrastructure-app: "Infrastructure app" + siem-app: "SIEM app" + security-app: "Elastic Security app" + ml-app: "Machine Learning" + dev-tools-app: "Dev Tools" + ingest-manager-app: "Ingest Manager" + stack-manage-app: "Stack Management" + stack-monitor-app: "Stack Monitoring" + alerts-ui: "Alerts and Actions" + rules-ui: "Rules" + rac-ui: "Rules and Connectors" + connectors-ui: "Connectors" + connectors-feature: "Actions and Connectors" + stack-rules-feature: "Stack Rules" + user-experience: "User Experience" + ems: "Elastic Maps Service" + ems-init: "EMS" + hosted-ems: "Elastic Maps Server" + ipm-app: "Index Pattern Management" + ingest-pipelines: "ingest pipelines" + ingest-pipelines-app: "Ingest Pipelines" + ingest-pipelines-cap: "Ingest pipelines" + ls-pipelines: "Logstash pipelines" + ls-pipelines-app: "Logstash Pipelines" + maint-windows: "maintenance windows" + maint-windows-app: "Maintenance Windows" + maint-windows-cap: "Maintenance windows" + custom-roles-app: "Custom Roles" + data-source: "data view" + data-sources: "data views" + data-source-caps: "Data View" + data-sources-caps: "Data Views" + data-source-cap: "Data view" + data-sources-cap: "Data views" + project-settings: "Project settings" + manage-app: "Management" + index-manage-app: "Index Management" + data-views-app: "Data Views" + rules-app: "Rules" + saved-objects-app: "Saved Objects" + tags-app: "Tags" + api-keys-app: "API keys" + transforms-app: "Transforms" + connectors-app: "Connectors" + files-app: "Files" + reports-app: "Reports" + maps-app: "Maps" + alerts-app: "Alerts" + crawler: "Enterprise Search web crawler" + ents: "Enterprise Search" + app-search-crawler: "App Search web crawler" + agent: "Elastic Agent" + agents: "Elastic Agents" + fleet: "Fleet" + fleet-server: "Fleet Server" + integrations-server: "Integrations Server" + ingest-manager: "Ingest Manager" + ingest-management: "ingest management" + package-manager: "Elastic Package Manager" + integrations: "Integrations" + package-registry: "Elastic Package Registry" + artifact-registry: "Elastic Artifact Registry" + aws: "AWS" + stack: "Elastic Stack" + xpack: "X-Pack" + es: "Elasticsearch" + kib: "Kibana" + esms: "Elastic Stack Monitoring Service" + esms-init: "ESMS" + ls: "Logstash" + beats: "Beats" + auditbeat: "Auditbeat" + filebeat: "Filebeat" + heartbeat: "Heartbeat" + metricbeat: "Metricbeat" + packetbeat: "Packetbeat" + winlogbeat: "Winlogbeat" + functionbeat: "Functionbeat" + journalbeat: "Journalbeat" + es-sql: "Elasticsearch SQL" + esql: "ES|QL" + elastic-agent: "Elastic Agent" + k8s: "Kubernetes" + log-driver-long: "Elastic Logging Plugin for Docker" + security: "X-Pack security" + security-features: "security features" + operator-feature: "operator privileges feature" + es-security-features: "Elasticsearch security features" + stack-security-features: "Elastic Stack security features" + endpoint-sec: "Endpoint Security" + endpoint-cloud-sec: "Endpoint and Cloud Security" + elastic-defend: "Elastic Defend" + elastic-sec: "Elastic Security" + elastic-endpoint: "Elastic Endpoint" + swimlane: "Swimlane" + sn: "ServiceNow" + sn-itsm: "ServiceNow ITSM" + sn-itom: "ServiceNow ITOM" + sn-sir: "ServiceNow SecOps" + jira: "Jira" + ibm-r: "IBM Resilient" + webhook: "Webhook" + webhook-cm: "Webhook - Case Management" + opsgenie: "Opsgenie" + bedrock: "Amazon Bedrock" + gemini: "Google Gemini" + hive: "TheHive" + monitoring: "X-Pack monitoring" + monitor-features: "monitoring features" + stack-monitor-features: "Elastic Stack monitoring features" + watcher: "Watcher" + alert-features: "alerting features" + reporting: "X-Pack reporting" + report-features: "reporting features" + graph: "X-Pack graph" + graph-features: "graph analytics features" + searchprofiler: "Search Profiler" + xpackml: "X-Pack machine learning" + ml: "machine learning" + ml-cap: "Machine learning" + ml-init: "ML" + ml-features: "machine learning features" + stack-ml-features: "Elastic Stack machine learning features" + ccr: "cross-cluster replication" + ccr-cap: "Cross-cluster replication" + ccr-init: "CCR" + ccs: "cross-cluster search" + ccs-cap: "Cross-cluster search" + ccs-init: "CCS" + ilm: "index lifecycle management" + ilm-cap: "Index lifecycle management" + ilm-init: "ILM" + dlm: "data lifecycle management" + dlm-cap: "Data lifecycle management" + dlm-init: "DLM" + search-snap: "searchable snapshot" + search-snaps: "searchable snapshots" + search-snaps-cap: "Searchable snapshots" + slm: "snapshot lifecycle management" + slm-cap: "Snapshot lifecycle management" + slm-init: "SLM" + rollup-features: "data rollup features" + ipm: "index pattern management" + ipm-cap: "Index pattern" + rollup: "rollup" + rollup-cap: "Rollup" + rollups: "rollups" + rollups-cap: "Rollups" + rollup-job: "rollup job" + rollup-jobs: "rollup jobs" + rollup-jobs-cap: "Rollup jobs" + dfeed: "datafeed" + dfeeds: "datafeeds" + dfeed-cap: "Datafeed" + dfeeds-cap: "Datafeeds" + ml-jobs: "machine learning jobs" + ml-jobs-cap: "Machine learning jobs" + anomaly-detect: "anomaly detection" + anomaly-detect-cap: "Anomaly detection" + anomaly-job: "anomaly detection job" + anomaly-jobs: "anomaly detection jobs" + anomaly-jobs-cap: "Anomaly detection jobs" + dataframe: "data frame" + dataframes: "data frames" + dataframe-cap: "Data frame" + dataframes-cap: "Data frames" + watcher-transform: "payload transform" + watcher-transforms: "payload transforms" + watcher-transform-cap: "Payload transform" + watcher-transforms-cap: "Payload transforms" + transform: "transform" + transforms: "transforms" + transform-cap: "Transform" + transforms-cap: "Transforms" + dataframe-transform: "transform" + dataframe-transform-cap: "Transform" + dataframe-transforms: "transforms" + dataframe-transforms-cap: "Transforms" + dfanalytics-cap: "Data frame analytics" + dfanalytics: "data frame analytics" + dataframe-analytics-config: "'{dataframe} analytics config'" + dfanalytics-job: "'{dataframe} analytics job'" + dfanalytics-jobs: "'{dataframe} analytics jobs'" + dfanalytics-jobs-cap: "'{dataframe-cap} analytics jobs'" + cdataframe: "continuous data frame" + cdataframes: "continuous data frames" + cdataframe-cap: "Continuous data frame" + cdataframes-cap: "Continuous data frames" + cdataframe-transform: "continuous transform" + cdataframe-transforms: "continuous transforms" + cdataframe-transforms-cap: "Continuous transforms" + ctransform: "continuous transform" + ctransform-cap: "Continuous transform" + ctransforms: "continuous transforms" + ctransforms-cap: "Continuous transforms" + oldetection: "outlier detection" + oldetection-cap: "Outlier detection" + olscore: "outlier score" + olscores: "outlier scores" + fiscore: "feature influence score" + evaluatedf-api: "evaluate {dataframe} analytics API" + evaluatedf-api-cap: "Evaluate {dataframe} analytics API" + binarysc: "binary soft classification" + binarysc-cap: "Binary soft classification" + regression: "regression" + regression-cap: "Regression" + reganalysis: "regression analysis" + reganalysis-cap: "Regression analysis" + depvar: "dependent variable" + feature-var: "feature variable" + feature-vars: "feature variables" + feature-vars-cap: "Feature variables" + classification: "classification" + classification-cap: "Classification" + classanalysis: "classification analysis" + classanalysis-cap: "Classification analysis" + infer-cap: "Inference" + infer: "inference" + lang-ident-cap: "Language identification" + lang-ident: "language identification" + data-viz: "Data Visualizer" + file-data-viz: "File Data Visualizer" + feat-imp: "feature importance" + feat-imp-cap: "Feature importance" + nlp: "natural language processing" + nlp-cap: "Natural language processing" + apm-agent: "APM agent" + apm-go-agent: "Elastic APM Go agent" + apm-go-agents: "Elastic APM Go agents" + apm-ios-agent: "Elastic APM iOS agent" + apm-ios-agents: "Elastic APM iOS agents" + apm-java-agent: "Elastic APM Java agent" + apm-java-agents: "Elastic APM Java agents" + apm-dotnet-agent: "Elastic APM .NET agent" + apm-dotnet-agents: "Elastic APM .NET agents" + apm-node-agent: "Elastic APM Node.js agent" + apm-node-agents: "Elastic APM Node.js agents" + apm-php-agent: "Elastic APM PHP agent" + apm-php-agents: "Elastic APM PHP agents" + apm-py-agent: "Elastic APM Python agent" + apm-py-agents: "Elastic APM Python agents" + apm-ruby-agent: "Elastic APM Ruby agent" + apm-ruby-agents: "Elastic APM Ruby agents" + apm-rum-agent: "Elastic APM Real User Monitoring (RUM) JavaScript agent" + apm-rum-agents: "Elastic APM RUM JavaScript agents" + apm-lambda-ext: "Elastic APM AWS Lambda extension" + project-monitors: "project monitors" + project-monitors-cap: "Project monitors" + private-location: "Private Location" + private-locations: "Private Locations" + pwd: "YOUR_PASSWORD" + esh: "ES-Hadoop" + default-dist: "default distribution" + oss-dist: "OSS-only distribution" + observability: "Observability" + api-request-title: "Request" + api-prereq-title: "Prerequisites" + api-description-title: "Description" + api-path-parms-title: "Path parameters" + api-query-parms-title: "Query parameters" + api-request-body-title: "Request body" + api-response-codes-title: "Response codes" + api-response-body-title: "Response body" + api-example-title: "Example" + api-examples-title: "Examples" + api-definitions-title: "Properties" + multi-arg: "†footnoteref:[multi-arg,This parameter accepts multiple arguments.]" + multi-arg-ref: "†footnoteref:[multi-arg]" + yes-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png[Yes,20,15]" + no-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png[No,20,15]" + es-repo: "https://github.com/elastic/elasticsearch/" + es-issue: "https://github.com/elastic/elasticsearch/issues/" + es-pull: "https://github.com/elastic/elasticsearch/pull/" + es-commit: "https://github.com/elastic/elasticsearch/commit/" + kib-repo: "https://github.com/elastic/kibana/" + kib-issue: "https://github.com/elastic/kibana/issues/" + kibana-issue: "'{kib-repo}issues/'" + kib-pull: "https://github.com/elastic/kibana/pull/" + kibana-pull: "'{kib-repo}pull/'" + kib-commit: "https://github.com/elastic/kibana/commit/" + ml-repo: "https://github.com/elastic/ml-cpp/" + ml-issue: "https://github.com/elastic/ml-cpp/issues/" + ml-pull: "https://github.com/elastic/ml-cpp/pull/" + ml-commit: "https://github.com/elastic/ml-cpp/commit/" + apm-repo: "https://github.com/elastic/apm-server/" + apm-issue: "https://github.com/elastic/apm-server/issues/" + apm-pull: "https://github.com/elastic/apm-server/pull/" + kibana-blob: "https://github.com/elastic/kibana/blob/current/" + apm-get-started-ref: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-server-ref: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-v: "https://www.elastic.co/guide/en/apm/server/current" + apm-server-ref-m: "https://www.elastic.co/guide/en/apm/server/master" + apm-server-ref-62: "https://www.elastic.co/guide/en/apm/server/6.2" + apm-server-ref-64: "https://www.elastic.co/guide/en/apm/server/6.4" + apm-server-ref-70: "https://www.elastic.co/guide/en/apm/server/7.0" + apm-overview-ref-v: "https://www.elastic.co/guide/en/apm/get-started/current" + apm-overview-ref-70: "https://www.elastic.co/guide/en/apm/get-started/7.0" + apm-overview-ref-m: "https://www.elastic.co/guide/en/apm/get-started/master" + infra-guide: "https://www.elastic.co/guide/en/infrastructure/guide/current" + a-data-source: "a data view" + icon-bug: "pass:[]" + icon-checkInCircleFilled: "pass:[]" + icon-warningFilled: "pass:[]" diff --git a/docs/index.asciidoc b/docs/index.asciidoc deleted file mode 100644 index cc4d67334..000000000 --- a/docs/index.asciidoc +++ /dev/null @@ -1,27 +0,0 @@ -include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -// :branch: current - -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/agent/go[elastic.co] -endif::[] - -= APM Go Agent Reference - -ifndef::env-github[] -include::./introduction.asciidoc[Introduction] -include::./set-up.asciidoc[Set up] -include::./supported-tech.asciidoc[Supported Technologies] -include::./configuration.asciidoc[Configuration] -include::./api.asciidoc[API documentation] -include::./metrics.asciidoc[Metrics] -include::./logs.asciidoc[Log Correlation] -include::./opentelemetry.asciidoc[OpenTelemetry API] -include::./opentracing.asciidoc[OpenTracing API] -include::./contributing.asciidoc[Contributing] -include::./troubleshooting.asciidoc[Troubleshooting] -include::./upgrading.asciidoc[Upgrading] -include::./release-notes.asciidoc[Release notes] -include::./redirects.asciidoc[] -endif::[] diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc deleted file mode 100644 index 439eb022f..000000000 --- a/docs/introduction.asciidoc +++ /dev/null @@ -1,52 +0,0 @@ -*NOTE*: This repository is in maintenance mode. Bug fixes will continue to be -applied, but no new features will be implemented. To replace this agent, we -recommend you to -https://www.elastic.co/blog/elastic-go-apm-agent-to-opentelemetry-go-sdk[migrate -to the OpenTelemetry Go API and SDK], which provides similar features. In order -to help you do a seamless migration, we recommend using our -https://www.elastic.co/guide/en/apm/agent/go/current/opentelemetry.html[OpenTelemetry -Bridge]. Please refer to the blog post above for further details. - -[[introduction]] -== Introduction - -The Elastic APM Go Agent enables you to trace the execution of operations in your https://golang.org/[Go] -applications, sending performance metrics and errors to the Elastic APM server. -It has built-in support for popular frameworks and toolkits, -like http://www.gorillatoolkit.org/[Gorilla] and https://gin-gonic.com/[Gin], -as well as support for instrumenting Go's built-in https://golang.org/pkg/net/http/[net/http], -https://golang.org/pkg/database/sql/[database/sql] drivers. -The Agent also offers an <> for custom instrumentation. - -[float] -[[how-it-works]] -=== How does the Agent work? - -The Agent includes instrumentation modules for <>, -each providing middleware or wrappers for recording interesting events, such as incoming HTTP requests, outgoing HTTP requests, and database queries. - -To collect data about incoming HTTP requests, install router middleware for one of the supported <>. -Incoming requests will be recorded as transactions, along with any related panics or errors. - -To collect data for outgoing HTTP requests, instrument an `http.Client` or `http.Transport` using <>. -To collect data about database queries, use <>, -which provides instrumentation for well known database drivers. - -In order to connect transactions with related spans and errors, and propagate traces between services (distributed tracing), -the agent relies on Go's built-in https://golang.org/pkg/context/[context] package: -transactions and spans are stored in context objects. -For example, for incoming HTTP requests, in-flight trace data will be recorded in the `context` object accessible through -https://golang.org/pkg/net/http/#Request.Context[net/http.Context]. -Read more about this in <>. - -In addition to capturing events like those mentioned above, -the agent also collects system and application metrics at regular intervals. -This collection happens in a background goroutine that is automatically started when the agent is initialized. - -[float] -[[additional-components]] -=== Additional Components - -APM Agents work in conjunction with the {apm-guide-ref}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana]. -The {apm-guide-ref}/index.html[APM Guide] provides details on how these components work together, -and provides a matrix outlining {apm-guide-ref}/agent-server-compatibility.html[Agent and Server compatibility]. diff --git a/docs/logs.asciidoc b/docs/logs.asciidoc deleted file mode 100644 index 8c08201e9..000000000 --- a/docs/logs.asciidoc +++ /dev/null @@ -1,140 +0,0 @@ -[[logs]] -== Logs - -Elastic APM Go Agent provides <>. -The agent will automaticaly inject correlation IDs that allow navigation between logs, traces and services. - -This features is part of {observability-guide}/application-logs.html[Application log ingestion strategies]. - -The {ecs-logging-go-logrus-ref}/intro.html[`ecslogrus`] and {ecs-logging-go-zap-ref}/intro.html[`ecszap`] libraries can also be used to use the {ecs-logging-ref}/intro.html[ECS logging] format without an APM agent. -When deployed with the Go APM agent, the agent will provide <> IDs. - -The Go agent provides integrations for popular logging frameworks that -inject trace ID fields into the application's log records. You can find a list of -the supported logging frameworks under <>. - -If your favorite logging framework is not already supported, there are two other options: - -* Open a feature request, or contribute code, for additional support as described in <>. -* Manually inject trace IDs into log records, as described below in <>. - -[[log-correlation-ids]] -== Log Correlation - -{apm-guide-ref}/log-correlation.html[Log correlation] allows you to navigate to all logs belonging to a particular trace -and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided. - -In order to correlate logs from your app with transactions captured by the -Elastic APM Go Agent, your logs must contain one or more of the following identifiers: - -* {ecs-ref}/ecs-tracing.html[`transaction.id`] -* {ecs-ref}/ecs-tracing.html[`trace.id`] -* {ecs-ref}/ecs-error.html[`span.id`] - -In order to correlate the logs to the service and environment, the logs should also contain the -following fields: - -- {ecs-ref}/ecs-service.html[`service.name`] -- {ecs-ref}/ecs-service.html[`service.version`] -- {ecs-ref}/ecs-service.html[`service.environment`] - -[float] -[[log-correlation-manual]] -=== Manual log correlation - -If the agent-provided logging integrations are not suitable or not available for your -application, then you can use the agent's <> to inject trace IDs manually. -There are two main approaches you can take, depending on whether you are using structured -or unstructured logging. - -[float] -[[log-correlation-manual-structured]] -==== Manual log correlation (structured) - -For correlating structured logs with traces and services, the fields defined <> -should be added to logs. - -Given a transaction object, you can obtain its trace ID and transaction ID using -the <> method. Similarly, -given a span object, you can obtain its span ID using <>. - -If you use the context APIs to start transactions and spans, then you can obtain -the context's current transaction using <>, -and current span using <>. Note that if -a transaction is not sampled, `apm.TransactionFromContext` will return `nil`. -Similarly, spans may be dropped by the agent, so `apm.SpanFromContext` may also return `nil`. - -[source,go] ----- -labels := make(map[string]string) -tx := apm.TransactionFromContext(ctx) -if tx != nil { - traceContext := tx.TraceContext() - labels["trace.id"] = traceContext.Trace.String() - labels["transaction.id"] = traceContext.Span.String() - if span := apm.SpanFromContext(ctx); span != nil { - labels["span.id"] = span.TraceContext().Span - } -} ----- - -Follow this article to ingest JSON-encoded logs with Filebeat: -{blog-ref}how-to-instrument-your-go-app-with-the-elastic-apm-go-agent#logs[How to instrument your Go app with the Elastic APM Go agent]. - -[float] -[[log-correlation-manual-unstructured]] -==== Manual log correlation (unstructured) - -For correlating unstructured logs (e.g. basic printf-style logging, like the standard library's -`log` package), then you will need to need to include the trace IDs in your log message. Then, -extract them using Filebeat. - -If you already have a transaction or span object, use the -<> or <> -methods. The trace, transaction, and span ID types all provide `String` methods that yield -their canonical hex-encoded string representation. - -[source,go] ----- -traceContext := tx.TraceContext() -spanID := span.TraceContext().Span -log.Printf("ERROR [trace.id=%s transaction.id=%s span.id=%s] an error occurred", traceContext.Trace, traceContext.Span, spanID) ----- - - -If instead you are dealing with context objects, you may prefer to use the -<> function. For example, you could supply it as an argument -to `log.Printf` as follows: - -[source,go] ----- -log.Printf("ERROR [%+v] an error occurred", apm.TraceFormatter(ctx)) ----- - -This would print a log message along the lines of: - - 2019/09/17 14:48:02 ERROR [trace.id=cd04f33b9c0c35ae8abe77e799f126b7 transaction.id=cd04f33b9c0c35ae span.id=960834f4538880a4] an error occurred - -For log correlation to work, the trace IDs must be extracted from the log message and -stored in separate fields in the Elasticsearch document. This can be achieved by -{filebeat-ref}/configuring-ingest-node.html[using an ingest pipeline to parse the data], in particular -by using {ref}/grok-processor.html[the grok processor]. - -[source,json] ----- -{ - "description": "...", - "processors": [ - { - "grok": { - "field": "message", - "patterns": ["%{YEAR}/%{MONTHNUM}/%{MONTHDAY} %{TIME} %{LOGLEVEL:log.level} \\[trace.id=%{TRACE_ID:trace.id}(?: transaction.id=%{SPAN_ID:transaction.id})?(?: span.id=%{SPAN_ID:span.id})?\\] %{GREEDYDATA:message}"], - "pattern_definitions": { - "TRACE_ID": "[0-9A-Fa-f]{32}", - "SPAN_ID": "[0-9A-Fa-f]{16}" - } - } - } - ] -} ----- diff --git a/docs/metrics.asciidoc b/docs/metrics.asciidoc deleted file mode 100644 index b69d371e6..000000000 --- a/docs/metrics.asciidoc +++ /dev/null @@ -1,311 +0,0 @@ -[[metrics]] -== Metrics - -The Go agent periodically gathers and reports metrics. Control how -often metrics are reported with the <> configuration, -and disable metrics with <>. - -[float] -[[metrics-system]] -=== System metrics - -The Go agent reports basic system-level and process-level CPU and memory metrics. -For more system metrics, consider installing {metricbeat-ref}/index.html[Metricbeat] -on your hosts. - -As of Elastic Stack version 6.6, these metrics will be visualized in the APM app. - -In some cases data from multiple nodes will be combined. As of Elastic Stack version 7.5, -you will be able to set a unique name for each node to avoid this problem. -Otherwise, data will be aggregated separately based on container ID or host name. - -*`system.cpu.total.norm.pct`*:: -+ --- -type: scaled_float - -format: percent - -The percentage of CPU time in states other than Idle and IOWait, normalised by the number of cores. --- - - -*`system.process.cpu.total.norm.pct`*:: -+ --- -type: scaled_float - -format: percent - -The percentage of CPU time spent by the process since the last event. -This value is normalized by the number of CPU cores and it ranges from 0 to 100%. --- - - -*`system.memory.total`*:: -+ --- -type: long - -format: bytes - -Total memory. --- - - -*`system.memory.actual.free`*:: -+ --- -type: long - -format: bytes - -The actual memory in bytes. It is calculated based on the OS. -On Linux it consists of the free memory plus caches and buffers. -On OSX it is a sum of free memory and the inactive memory. -On Windows, this value does not include memory consumed by system caches and buffers. --- - - -*`system.process.memory.size`*:: -+ --- -type: long - -format: bytes - -The total virtual memory the process has. --- - -[float] -[[metrics-golang]] -=== Go runtime metrics - -The Go agent reports various Go runtime metrics. - -NOTE: As of now, there are no built-in visualizations for these metrics, -so you will need to create custom Kibana dashboards for them. - -*`golang.goroutines`*:: -+ --- -type: long - -The number of goroutines that currently exist. --- - - -*`golang.heap.allocations.mallocs`*:: -+ --- -type: long - -The number of mallocs. --- - - -*`golang.heap.allocations.frees`*:: -+ --- -type: long - -The number of frees. --- - - -*`golang.heap.allocations.objects`*:: -+ --- -type: long - -The total number of allocated objects. --- - - -*`golang.heap.allocations.total`*:: -+ --- -type: long - -format: bytes - -Bytes allocated (even if freed) throughout the lifetime. --- - - -*`golang.heap.allocations.allocated`*:: -+ --- -type: long - -format: bytes - -Bytes allocated and not yet freed (same as Alloc from https://golang.org/pkg/runtime/#MemStats[runtime.MemStats]). --- - - -*`golang.heap.allocations.idle`*:: -+ --- -type: long - -format: bytes - -Bytes in idle spans. --- - - -*`golang.heap.allocations.active`*:: -+ --- -type: long - -format: bytes - -Bytes in non-idle spans. --- - - -*`golang.heap.system.total`*:: -+ --- -type: long - -format: bytes - -Total bytes obtained from system (sum of XxxSys from https://golang.org/pkg/runtime/#MemStats[runtime.MemStats]). --- - - -*`golang.heap.system.obtained`*:: -+ --- -type: long - -format: bytes - -Via HeapSys from https://golang.org/pkg/runtime/#MemStats[runtime.MemStats], bytes obtained from system. -heap_sys = heap_idle + heap_inuse. --- - - -*`golang.heap.system.stack`*:: -+ --- -type: long - -format: bytes - -Bytes of stack memory obtained from the OS. --- - - -*`golang.heap.system.released`*:: -+ --- -type: long - -format: bytes - -Bytes released to the OS. --- - - -*`golang.heap.gc.total_pause.ns`*:: -+ --- -type: long - -The total garbage collection duration in nanoseconds. --- - - -*`golang.heap.gc.total_count`*:: -+ --- -type: long - -The total number of garbage collections. --- - - -*`golang.heap.gc.next_gc_limit`*:: -+ --- -type: long - -format: bytes - -Target heap size of the next garbage collection cycle. --- - - -*`golang.heap.gc.cpu_fraction`*:: -+ --- -type: float - -Fraction of CPU time used by garbage collection. --- - -[float] -[[metrics-application]] -=== Application Metrics - -*`transaction.duration`*:: -+ --- -type: simple timer - -This timer tracks the duration of transactions and allows for the creation of graphs displaying a weighted average. - -Fields: - -* `sum.us`: The sum of all transaction durations in microseconds since the last report (the delta) -* `count`: The count of all transactions since the last report (the delta) - -You can filter and group by these dimensions: - -* `transaction.name`: The name of the transaction -* `transaction.type`: The type of the transaction, for example `request` - --- - -*`transaction.breakdown.count`*:: -+ --- -type: long - -format: count (delta) - -The number of transactions for which breakdown metrics (`span.self_time`) have been created. -As the Go agent tracks the breakdown for both sampled and non-sampled transactions, this -metric is equivalent to `transaction.duration.count` - -You can filter and group by these dimensions: - -* `transaction.name`: The name of the transaction -* `transaction.type`: The type of the transaction, for example `request` - --- - -*`span.self_time`*:: -+ --- -type: simple timer - -This timer tracks the span self-times and is the basis of the transaction breakdown visualization. - -Fields: - -* `sum.us`: The sum of all span self-times in microseconds since the last report (the delta) -* `count`: The count of all span self-times since the last report (the delta) - -You can filter and group by these dimensions: - -* `transaction.name`: The name of the transaction -* `transaction.type`: The type of the transaction, for example `request` -* `span.type`: The type of the span, for example `app`, `template` or `db` -* `span.subtype`: The sub-type of the span, for example `mysql` (optional) - --- diff --git a/docs/opentracing.asciidoc b/docs/opentracing.asciidoc deleted file mode 100644 index 2f6f80ace..000000000 --- a/docs/opentracing.asciidoc +++ /dev/null @@ -1,139 +0,0 @@ -[[opentracing]] -== OpenTracing API - -The Elastic APM Go agent provides an implementation of the https://opentracing.io[OpenTracing API], -building on top of the core Elastic APM API. - -Spans created through the OpenTracing API will be translated to Elastic APM transactions or spans. -Root spans, and spans created with a remote span context, will be translated to Elastic APM -transactions. All others will be created as Elastic APM spans. - -[float] -[[opentracing-init]] -=== Initializing the tracer - -The OpenTracing API implementation is implemented as a bridge on top of the core Elastic APM API. -To initialize the OpenTracing tracer implementation, you must first import the `apmot` package: - -[source,go] ----- -import ( - "go.elastic.co/apm/module/apmot/v2" -) ----- - -The apmot package exports a function, "New", which returns an implementation of the -`opentracing.Tracer` interface. If you call `apmot.New()` without any arguments, -the returned tracer will wrap `apm.DefaultTracer()`. If you wish to use a different -`apm.Tracer`, then you can pass it with `apmot.New(apmot.WithTracer(t))`. - -[source,go] ----- -otTracer := apmot.New() ----- - -Once you have obtained an `opentracing.Tracer`, use the standard OpenTracing API -to report spans to Elastic APM. Please refer to https://github.com/opentracing/opentracing-go[opentracing-go] -for documentation on the OpenTracing Go API. - -[source,go] ----- -import ( - "context" - - "go.elastic.co/apm/module/apmot/v2" - - "github.com/opentracing/opentracing-go" -) - -func main() { - opentracing.SetGlobalTracer(apmot.New()) - - parent, ctx := opentracing.StartSpanFromContext(context.Background(), "parent") - child, _ := opentracing.StartSpanFromContext(ctx, "child") - child.Finish() - parent.Finish() -} ----- - -[float] -[[opentracing-mixed]] -=== Mixing Native and OpenTracing APIs - -When you import `apmot`, transactions and spans created with the <> -will be made available as OpenTracing spans, enabling you to mix the use of the -native and OpenTracing APIs. e.g.: - -[source,go] ----- -// Transaction created through native API. -transaction := apm.DefaultTracer().StartTransaction("GET /", "request") -ctx := apm.ContextWithTransaction(context.Background(), transaction) - -// Span created through OpenTracing API will be a child of the transaction. -otSpan, ctx := opentracing.StartSpanFromContext(ctx, "ot-span") - -// Span created through the native API will be a child of the span created -// above via the OpenTracing API. -apmSpan, ctx := apm.StartSpan(ctx, "apm-span", "apm-span") ----- - -The `opentracing.SpanFromContext` function will return an `opentracing.Span` -that wraps either an `apm.Span` or `apm.Transaction`. These span objects are -intended only for passing in context when creating a new span through the -OpenTracing API, and are not fully functional spans. In particular, the `Finish` -and `Log*` methods are no-ops, and the `Tracer` method returns a no-op tracer. - -[float] -[[opentracing-apm-tags]] -=== Elastic APM specific tags - -Elastic APM defines some tags which are not included in the OpenTracing API, -but are relevant in the context of Elastic APM. Some tags are relevant only -to Elastic APM transactions. - -- `type` - sets the type of the transaction or span, e.g. "request", or "ext.http". - If `type` is not specified, then the type may be inferred from other - tags. e.g. if "http.url" is specified, then the type will be "request" - for transactions, and "ext.http" for spans. If no type can be inferred, - it is set to "unknown". - -The following tags are relevant only to root or service-entry spans, which are -translated to Elastic APM transactions: - -- `user.id` - sets the user ID, which appears in the "User" tab in the transaction details in the Elastic APM app -- `user.email` - sets the user email, which appears in the "User" tab in the transaction details in the Elastic APM app -- `user.username` - sets the user name, which appears in the "User" tab in the transaction details in the Elastic APM app -- `result` - sets the result of the transaction. If `result` is _not_ specified, but `error` tag is set to `true`, - then the transaction result will be set to "error" - -[float] -[[opentracing-logs]] -=== Span Logs - -The `Span.LogKV` and `Span.LogFields` methods will send error events to Elastic APM for logs -with the "event" field set to "error". - -The deprecated log methods `Span.Log`, `Span.LogEvent`, and `Span.LogEventWithPayload` are no-ops. - -[float] -[[opentracing-caveats]] -=== Caveats - -[float] -[[opentracing-caveats-propagation]] -==== Context Propagation - -We support the `TextMap` and `HTTPHeaders` propagation formats; `Binary` is not currently supported. - -[float] -[[opentracing-caveats-spanrefs]] -==== Span References - -We support only `ChildOf` references. Other references, e.g. `FollowsFrom`, are not currently supported. - -[float] -[[opentracing-caveats-baggage]] -==== Baggage - -`Span.SetBaggageItem` is a no-op; baggage items are silently dropped. diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc deleted file mode 100644 index 9f4a61aff..000000000 --- a/docs/redirects.asciidoc +++ /dev/null @@ -1,9 +0,0 @@ -["appendix",role="exclude",id="redirects"] -= Deleted pages - -The following pages have moved or been deleted. - -[role="exclude",id="log-correlation"] -=== Log correlation - -This section has moved. See <>. diff --git a/docs/reference/api-documentation.md b/docs/reference/api-documentation.md new file mode 100644 index 000000000..90c8920fa --- /dev/null +++ b/docs/reference/api-documentation.md @@ -0,0 +1,459 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/api.html +--- + +# API documentation [api] + +This section describes the most commonly used parts of the API. + +The Go agent is documented using standard godoc. For complete documentation, refer to the documentation at [pkg.go.dev/go.elastic.co/apm/v2](https://pkg.go.dev/go.elastic.co/apm/v2), or by using the "godoc" tool. + + +## Tracer API [tracer-api] + +The initial point of contact your application will have with the Go agent is the `apm.Tracer` type, which provides methods for reporting transactions and errors. + +To make instrumentation simpler, the Go agent provides an initialization function, `apm.DefaultTracer()`. This tracer is initialized the first time `apm.DefaultTracer()` is called, and returned on subsequent calls. The tracer returned by this function can be modified using `apm.SetDefaultTracer(tracer)`. Calling this will close the previous default tracer, if any exists. This tracer is configured with environment variables; see [*Configuration*](/reference/configuration.md) for details. + +```go +import ( + "go.elastic.co/apm/v2" +) + +func main() { + tracer := apm.DefaultTracer() + ... +} +``` + + +## Transactions [transaction-api] + + +### `func (*Tracer) StartTransaction(name, type string) *Transaction` [tracer-api-start-transaction] + +StartTransaction returns a new Transaction with the specified name and type, and with the start time set to the current time. If you need to set the timestamp or the parent [trace context](#trace-context), use [Tracer.StartTransactionOptions](#tracer-api-start-transaction-options). + +This method should be called at the beginning of a transaction such as a web or RPC request. e.g.: + +```go +transaction := apm.DefaultTracer().StartTransaction("GET /", "request") +``` + +Transactions will be grouped by type and name in the Elastic APM app. + +After starting a transaction, you can record a result and add context to further describe the transaction. + +```go +transaction.Result = "Success" +transaction.Context.SetLabel("region", "us-east-1") +``` + +See [Context](#context-api) for more details on setting transaction context. + + +### `func (*Tracer) StartTransactionOptions(name, type string, opts TransactionOptions) *Transaction` [tracer-api-start-transaction-options] + +StartTransactionOptions is essentially the same as StartTransaction, but also accepts an options struct. This struct allows you to specify the parent [trace context](#trace-context) and/or the transaction’s start time. + +```go +opts := apm.TransactionOptions{ + Start: time.Now(), + TraceContext: parentTraceContext, +} +transaction := apm.DefaultTracer().StartTransactionOptions("GET /", "request", opts) +``` + + +### `func (*Transaction) End()` [transaction-end] + +End enqueues the transaction for sending to the Elastic APM server. The transaction must not be modified after this, but it may still be used for starting spans. + +The transaction’s duration is calculated as the amount of time elapsed between the start of the transaction and this call. To override this behavior, the transaction’s `Duration` field may be set before calling End. + +```go +transaction.End() +``` + + +### `func (*Transaction) TraceContext() TraceContext` [transaction-tracecontext] + +TraceContext returns the transaction’s [trace context](#trace-context). + + +### `func (*Transaction) EnsureParent() SpanID` [transaction-ensureparent] + +EnsureParent returns the transaction’s parent span ID—​generating and recording one if it did not previously have one. + +EnsureParent enables correlation with spans created by the JavaScript Real User Monitoring (RUM) agent for the initial page load. If your backend service generates the HTML page dynamically, you can inject the trace and parent span ID into the page in order to initialize the JavaScript RUM agent, such that the web browser’s page load appears as the root of the trace. + +```go +var initialPageTemplate = template.Must(template.New("").Parse(` + + + + + +... + +`)) + +func initialPageHandler(w http.ResponseWriter, req *http.Request) { + err := initialPageTemplate.Execute(w, apm.TransactionFromContext(req.Context())) + if err != nil { + ... + } +} +``` + +See the [JavaScript RUM agent documentation](apm-agent-rum-js://reference/index.md) for more information. + + +### `func (*Transaction) ParentID() SpanID` [transaction-parentid] + +ParentID returns the ID of the transaction’s parent, or a zero (invalid) SpanID if the transaction has no parent. + + +### `func ContextWithTransaction(context.Context, *Transaction) context.Context` [apm-context-with-transaction] + +ContextWithTransaction adds the transaction to the context, and returns the resulting context. + +The transaction can be retrieved using [apm.TransactionFromContext](#apm-transaction-from-context). The context may also be passed into [apm.StartSpan](#apm-start-span), which uses TransactionFromContext under the covers to create a span as a child of the transaction. + + +### `func TransactionFromContext(context.Context) *Transaction` [apm-transaction-from-context] + +TransactionFromContext returns a transaction previously stored in the context using [apm.ContextWithTransaction](#apm-context-with-transaction), or nil if the context does not contain a transaction. + + +### `func DetachedContext(context.Context) context.Context` [apm-detached-context] + +DetachedContext returns a new context detached from the lifetime of the input, but which still returns the same values as the input. + +DetachedContext can be used to maintain trace context required to correlate events, but where the operation is "fire-and-forget" and should not be affected by the deadline or cancellation of the surrounding context. + + +### `func TraceFormatter(context.Context) fmt.Formatter` [apm-traceformatter] + +TraceFormatter returns an implementation of [fmt.Formatter](https://golang.org/pkg/fmt/#Formatter) that can be used to format the IDs of the transaction and span stored in the provided context. + +The formatter understands the following formats: + +* %v: trace ID, transaction ID, and (if in the context of a span) span ID, space separated +* %t: trace ID only +* %x: transaction ID only +* %s: span ID only + +The "+" option can be used to format the values in "key=value" style, with the field names `trace.id`, `transaction.id`, and `span.id`. For example, using "%+v" as the format would yield "trace.id=…​ transaction.id=…​ span.id=…​". + +For a more in-depth example, see [Manual log correlation (unstructured)](/reference/log-correlation.md#log-correlation-manual-unstructured). + + +## Spans [span-api] + +To describe an activity within a transaction, we create spans. The Go agent has built-in support for generating spans for some activities, such as database queries. You can use the API to report spans specific to your application. + + +### `func (*Transaction) StartSpan(name, spanType string, parent *Span) *Span` [transaction-start-span] + +StartSpan starts and returns a new Span within the transaction, with the specified name, type, and optional parent span, and with the start time set to the current time. If you need to set the timestamp or parent [trace context](#trace-context), use [Transaction.StartSpanOptions](#transaction-start-span-options). + +If the span type contains two dots, they are assumed to separate the span type, subtype, and action; a single dot separates span type and subtype, and the action will not be set. + +If the transaction is sampled, then the span’s ID will be set, and its stacktrace will be set if the tracer is configured accordingly. If the transaction is not sampled, then the returned span will be silently discarded when its End method is called. To avoid any unnecessary computation for these dropped spans, call the [Dropped](#span-dropped) method. + +As a convenience, it is valid to create a span on a nil Transaction; the resulting span will be non-nil and safe for use, but will not be reported to the APM server. + +```go +span := tx.StartSpan("SELECT FROM foo", "db.mysql.query", nil) +``` + + +### `func (*Transaction) StartSpanOptions(name, spanType string, opts SpanOptions) *Span` [transaction-start-span-options] + +StartSpanOptions is essentially the same as StartSpan, but also accepts an options struct. This struct allows you to specify the parent [trace context](#trace-context) and/or the spans’s start time. If the parent trace context is not specified in the options, then the span will be a direct child of the transaction. Otherwise, the parent trace context should belong to some span descended from the transaction. + +```go +opts := apm.SpanOptions{ + Start: time.Now(), + Parent: parentSpan.TraceContext(), +} +span := tx.StartSpanOptions("SELECT FROM foo", "db.mysql.query", opts) +``` + + +### `func StartSpan(ctx context.Context, name, spanType string) (*Span, context.Context)` [apm-start-span] + +StartSpan starts and returns a new Span within the sampled transaction and parent span in the context, if any. If the span isn’t dropped, it will be included in the resulting context. + +```go +span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query") +``` + + +### `func (*Span) End()` [span-end] + +End marks the span as complete. The Span must not be modified after this, but may still be used as the parent of a span. + +The span’s duration will be calculated as the amount of time elapsed since the span was started until this call. To override this behaviour, the span’s Duration field may be set before calling End. + + +### `func (*Span) Dropped() bool` [span-dropped] + +Dropped indicates whether or not the span is dropped, meaning it will not be reported to the APM server. Spans are dropped when the created with a nil, or non-sampled transaction, or one whose max spans limit has been reached. + + +### `func (*Span) TraceContext() TraceContext` [span-tracecontext] + +TraceContext returns the span’s [trace context](#trace-context). + + +### `func ContextWithSpan(context.Context, *Span) context.Context` [apm-context-with-span] + +ContextWithSpan adds the span to the context and returns the resulting context. + +The span can be retrieved using [apm.SpanFromContext](#apm-span-from-context). The context may also be passed into [apm.StartSpan](#apm-start-span), which uses SpanFromContext under the covers to create another span as a child of the span. + + +### `func SpanFromContext(context.Context) *Span` [apm-span-from-context] + +SpanFromContext returns a span previously stored in the context using [apm.ContextWithSpan](#apm-context-with-span), or nil if the context does not contain a span. + + +### `func (*Span) ParentID() SpanID` [span-parentid] + +ParentID returns the ID of the span’s parent. + + +## Context [context-api] + +When reporting transactions and errors you can provide context to describe those events. Built-in instrumentation will typically provide some context, e.g. the URL and remote address for an HTTP request. You can also provide custom context and tags. + + +### `func (*Context) SetLabel(key string, value interface{})` [context-set-label] + +SetLabel labels the transaction or error with the given key and value. If the key contains any special characters (`.`, `*`, `"`), they will be replaced with underscores. + +If the value is numerical or boolean, then it will be sent to the server as a JSON number or boolean; otherwise it will converted to a string, using `fmt.Sprint` if necessary. Numerical and boolean values are supported by the server from version 6.7 onwards. + +String values longer than 1024 characters will be truncated. Labels are indexed in Elasticsearch as keyword fields. + +::::{tip} +Before using labels, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available. +:::: + + +::::{warning} +Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a [mapping explosion](docs-content://manage-data/data-store/mapping.md#mapping-limit-settings). +:::: + + + +### `func (*Context) SetCustom(key string, value interface{})` [context-set-custom] + +SetCustom is used to add custom, non-indexed, contextual information to transactions or errors. If the key contains any special characters (`.`, `*`, `"`), they will be replaced with underscores. + +Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors. + +The value can be of any type that can be encoded using `encoding/json`. + +::::{tip} +Before using custom context, ensure you understand the different types of [metadata](docs-content://solutions/observability/apps/metadata.md) that are available. +:::: + + + +### `func (*Context) SetUsername(username string)` [context-set-username] + +SetUsername records the username of the user associated with the transaction. + + +### `func (*Context) SetUserID(id string)` [context-set-user-id] + +SetUserID records the ID of the user associated with the transaction. + + +### `func (*Context) SetUserEmail(email string)` [context-set-user-email] + +SetUserEmail records the email address of the user associated with the transaction. + + +## Errors [error-api] + +Elastic APM provides two methods of capturing an error event: reporting an error log record, and reporting an "exception" (either a panic or an error in Go parlance). + + +### `func (*Tracer) NewError(error) *Error` [tracer-new-error] + +NewError returns a new Error with details taken from err. + +The exception message will be set to `err.Error()`. The exception module and type will be set to the package and type name of the cause of the error, respectively, where the cause has the same definition as given by [github.com/pkg/errors](https://github.com/pkg/errors). + +```go +e := apm.DefaultTracer().NewError(err) +... +e.Send() +``` + +The provided error can implement any of several interfaces to provide additional information: + +```go +// Errors implementing ErrorsStacktracer will have their stacktrace +// set based on the result of the StackTrace method. +type ErrorsStacktracer interface { + StackTrace() github.com/pkg/errors.StackTrace +} + +// Errors implementing Stacktracer will have their stacktrace +// set based on the result of the StackTrace method. +type Stacktracer interface { + StackTrace() []go.elastic.co/apm/v2/stacktrace.Frame +} + +// Errors implementing Typer will have a "type" field set to the +// result of the Type method. +type Typer interface { + Type() string +} + +// Errors implementing StringCoder will have a "code" field set to the +// result of the Code method. +type StringCoder interface { + Code() string +} + +// Errors implementing NumberCoder will have a "code" field set to the +// result of the Code method. +type NumberCoder interface { + Code() float64 +} +``` + +Errors created by with NewError will have their ID field populated with a unique ID. This can be used in your application for correlation. + + +### `func (*Tracer) NewErrorLog(ErrorLogRecord) *Error` [tracer-new-error-log] + +NewErrorLog returns a new Error for the given ErrorLogRecord: + +```go +type ErrorLogRecord struct { + // Message holds the message for the log record, + // e.g. "failed to connect to %s". + // + // If this is empty, "[EMPTY]" will be used. + Message string + + // MessageFormat holds the non-interpolated format + // of the log record, e.g. "failed to connect to %s". + // + // This is optional. + MessageFormat string + + // Level holds the severity level of the log record. + // + // This is optional. + Level string + + // LoggerName holds the name of the logger used. + // + // This is optional. + LoggerName string + + // Error is an error associated with the log record. + // + // This is optional. + Error error +} +``` + +The resulting Error’s log stacktrace will not be set. Call the SetStacktrace method to set it. + +```go +e := apm.DefaultTracer().NewErrorLog(apm.ErrorLogRecord{ + Message: "Somebody set up us the bomb.", +}) +... +e.Send() +``` + + +### `func (*Error) SetTransaction(*Transaction)` [error-set-transaction] + +SetTransaction associates the error with the given transaction. + + +### `func (*Error) SetSpan(*Span)` [error-set-span] + +SetSpan associates the error with the given span and the span’s transaction. When calling SetSpan, it is not necessary to also call SetTransaction. + + +### `func (*Error) Send()` [error-send] + +Send enqueues the error for sending to the Elastic APM server. + + +### `func (*Tracer) Recovered(interface{}) *Error` [tracer-recovered] + +Recovered returns an Error from the recovered value, optionally associating it with a transaction. The error is not sent; it is the caller’s responsibility to set the error’s context, and then call its `Send` method. + +```go +tx := apm.DefaultTracer().StartTransaction(...) +defer tx.End() +defer func() { + if v := recover(); v != nil { + e := apm.DefaultTracer().Recovered(v) + e.SetTransaction(tx) + e.Send() + } +}() +``` + + +### `func CaptureError(context.Context, error) *Error` [apm-captureerror] + +CaptureError returns a new error related to the sampled transaction and span present in the context, if any, and sets its exception details using the given error. The Error.Handled field will be set to true, and a stacktrace set. + +If there is no transaction in the context, or it is not being sampled, CaptureError returns nil. As a convenience, if the provided error is nil, then CaptureError will also return nil. + +```go +if err != nil { + e := apm.CaptureError(ctx, err) + e.Send() +} +``` + + +### Trace Context [trace-context] + +Trace context contains the ID for a transaction or span, the ID of the end-to-end trace to which the transaction or span belongs, and trace options such as flags relating to sampling. Trace context is propagated between processes, e.g. in HTTP headers, in order to correlate events originating from related services. + +Elastic APM’s trace context is based on the [W3C Trace Context](https://w3c.github.io/trace-context/) draft. + + +### Error Context [error-context] + +Errors can be associated with context just like transactions. See [Context](#context-api) for details. In addition, errors can be associated with an active transaction or span using [SetTransaction](#error-set-transaction) or [SetSpan](#error-set-span), respectively. + +```go +tx := apm.DefaultTracer().StartTransaction("GET /foo", "request") +defer tx.End() +e := apm.DefaultTracer().NewError(err) +e.SetTransaction(tx) +e.Send() +``` + + +### Tracer Config [tracer-config-api] + +Many configuration attributes can be be updated dynamically via `apm.Tracer` method calls. Please refer to the documentation at [pkg.go.dev/go.elastic.co/apm/v2#Tracer](https://pkg.go.dev/go.elastic.co/apm/v2#Tracer) for details. The configuration methods are primarily prefixed with `Set`, such as [apm#Tracer.SetLogger](https://pkg.go.dev/go.elastic.co/apm/v2#Tracer.SetLogger). + diff --git a/docs/instrumenting.asciidoc b/docs/reference/builtin-modules.md similarity index 52% rename from docs/instrumenting.asciidoc rename to docs/reference/builtin-modules.md index 983cd967e..f5632e660 100644 --- a/docs/instrumenting.asciidoc +++ b/docs/reference/builtin-modules.md @@ -1,49 +1,48 @@ -[[builtin-modules]] -=== Built-in instrumentation modules - -For each server instrumentation module, a transaction is reported for each handled -request. The transaction will be stored in the request context, which can be obtained through -that framework's API. The request context can be used for reporting <>. - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[[builtin-modules-apmhttp]] -==== module/apmhttp -Package apmhttp provides a low-level `net/http` middleware handler. Other web middleware should -typically be based off this. - -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request.Context[http.Request.Context] in your handler. - -[source,go] ----- +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/builtin-modules.html +--- + +# Built-in instrumentation modules [builtin-modules] + +For each server instrumentation module, a transaction is reported for each handled request. The transaction will be stored in the request context, which can be obtained through that framework’s API. The request context can be used for reporting [custom spans](/reference/custom-instrumentation.md#custom-instrumentation-spans). + +* [module/apmhttp](#builtin-modules-apmhttp) +* [module/apmfasthttp](#builtin-modules-apmfasthttp) +* [module/apmecho](#builtin-modules-apmecho) +* [module/apmgin](#builtin-modules-apmgin) +* [module/apmfiber](#builtin-modules-apmfiber) +* [module/apmbeego](#builtin-modules-apmbeego) +* [module/apmgorilla](#builtin-modules-apmgorilla) +* [module/apmgrpc](#builtin-modules-apmgrpc) +* [module/apmhttprouter](#builtin-modules-apmhttprouter) +* [module/apmnegroni](#builtin-modules-apmnegroni) +* [module/apmlambda](#builtin-modules-apmlambda) +* [module/apmsql](#builtin-modules-apmsql) +* [module/apmgopg](#builtin-modules-apmgopg) +* [module/apmgorm](#builtin-modules-apmgorm) +* [module/apmgocql](#builtin-modules-apmgocql) +* [module/apmredigo](#builtin-modules-apmredigo) +* [module/apmgoredis](#builtin-modules-apmgoredis) +* [module/apmgoredisv8](#builtin-modules-apmgoredisv8) +* [module/apmrestful](#builtin-modules-apmrestful) +* [module/apmchi](#builtin-modules-apmchi) +* [module/apmlogrus](#builtin-modules-apmlogrus) +* [module/apmzap](#builtin-modules-apmzap) +* [module/apmzerolog](#builtin-modules-apmzerolog) +* [module/apmelasticsearch](#builtin-modules-apmelasticsearch) +* [module/apmmongo](#builtin-modules-apmmongo) +* [module/apmawssdkgo](#builtin-modules-apmawssdkgo) +* [module/apmazure](#builtin-modules-apmazure) +* [module/apmpgx](#builtin-modules-apmpgx) + +## module/apmhttp [builtin-modules-apmhttp] + +Package apmhttp provides a low-level `net/http` middleware handler. Other web middleware should typically be based off this. + +For each request, a transaction is stored in the request context, which can be obtained via [http.Request.Context](https://golang.org/pkg/net/http/#Request.Context) in your handler. + +```go import ( "go.elastic.co/apm/module/apmhttp/v2" ) @@ -52,21 +51,15 @@ func main() { var myHandler http.Handler = ... tracedHandler := apmhttp.Wrap(myHandler) } ----- +``` The apmhttp handler will recover panics and send them to Elastic APM. -Package apmhttp also provides functions for instrumenting an `http.Client` or `http.RoundTripper` -such that outgoing requests are traced as spans, if the request context includes a transaction. -When performing the request, the enclosing context should be propagated by using -https://golang.org/pkg/net/http/#Request.WithContext[http.Request.WithContext], or a helper, such as those provided by https://golang.org/x/net/context/ctxhttp. +Package apmhttp also provides functions for instrumenting an `http.Client` or `http.RoundTripper` such that outgoing requests are traced as spans, if the request context includes a transaction. When performing the request, the enclosing context should be propagated by using [http.Request.WithContext](https://golang.org/pkg/net/http/#Request.WithContext), or a helper, such as those provided by [https://golang.org/x/net/context/ctxhttp](https://golang.org/x/net/context/ctxhttp). -Client spans are not ended until the response body is fully consumed or closed. -If you fail to do either, the span will not be sent. -Always close the response body to ensure HTTP connections can be reused; see https://golang.org/pkg/net/http/#Client.Do[`func (*Client) Do`]. +Client spans are not ended until the response body is fully consumed or closed. If you fail to do either, the span will not be sent. Always close the response body to ensure HTTP connections can be reused; see [`func (*Client) Do`](https://golang.org/pkg/net/http/#Client.Do). -[source,go] ----- +```go import ( "net/http" @@ -93,17 +86,16 @@ func serverHandler(w http.ResponseWriter, req *http.Request) { func main() { http.ListenAndServe(":8080", apmhttp.Wrap(http.HandlerFunc(serverHandler))) } ----- +``` -[[builtin-modules-apmfasthttp]] -==== module/apmfasthttp -Package apmfasthttp provides a low-level https://github.com/valyala/fasthttp[valyala/fasthttp] middleware request handler. Other fasthttp-based web middleware should typically be based off this. -For each request, a transaction is stored in the request context, which can be obtained via -https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx[fasthttp.RequestCtx] in your handler using `apm.TransactionFromContext`. +## module/apmfasthttp [builtin-modules-apmfasthttp] -[source,go] ----- +Package apmfasthttp provides a low-level [valyala/fasthttp](https://github.com/valyala/fasthttp) middleware request handler. Other fasthttp-based web middleware should typically be based off this. + +For each request, a transaction is stored in the request context, which can be obtained via [fasthttp.RequestCtx](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) in your handler using `apm.TransactionFromContext`. + +```go import ( "github.com/valyala/fasthttp" @@ -117,23 +109,20 @@ func main() { } tracedHandler := apmfasthttp.Wrap(myHandler) } ----- +``` The apmfasthttp handler will recover panics and send them to Elastic APM. -[[builtin-modules-apmecho]] -==== module/apmecho -Packages apmecho and apmechov4 provide middleware for the https://github.com/labstack/echo[Echo] -web framework, versions 3.x and 4.x respectively. -If you are using Echo 4.x (`github.com/labstack/echo/v4`), use `module/apmechov4`. -For the older Echo 3.x versions (`github.com/labstack/echo`), use `module/apmecho`. +## module/apmecho [builtin-modules-apmecho] + +Packages apmecho and apmechov4 provide middleware for the [Echo](https://github.com/labstack/echo) web framework, versions 3.x and 4.x respectively. -For each request, a transaction is stored in the request context, which can be obtained via -https://godoc.org/github.com/labstack/echo#Context[echo.Context]`.Request().Context()` in your handler. +If you are using Echo 4.x (`github.com/labstack/echo/v4`), use `module/apmechov4`. For the older Echo 3.x versions (`github.com/labstack/echo`), use `module/apmecho`. -[source,go] ----- +For each request, a transaction is stored in the request context, which can be obtained via [echo.Context](https://godoc.org/github.com/labstack/echo#Context)`.Request().Context()` in your handler. + +```go import ( echo "github.com/labstack/echo/v4" @@ -145,20 +134,18 @@ func main() { e.Use(apmechov4.Middleware()) ... } ----- +``` + +The middleware will recover panics and send them to Elastic APM, so you do not need to install the echo/middleware.Recover middleware. -The middleware will recover panics and send them to Elastic APM, so you do not need to install -the echo/middleware.Recover middleware. -[[builtin-modules-apmgin]] -==== module/apmgin -Package apmgin provides middleware for the https://gin-gonic.com/[Gin] web framework. +## module/apmgin [builtin-modules-apmgin] -For each request, a transaction is stored in the request context, which can be obtained via -https://godoc.org/github.com/gin-gonic/gin#Context[gin.Context]`.Request.Context()` in your handler. +Package apmgin provides middleware for the [Gin](https://gin-gonic.com/) web framework. -[source,go] ----- +For each request, a transaction is stored in the request context, which can be obtained via [gin.Context](https://godoc.org/github.com/gin-gonic/gin#Context)`.Request.Context()` in your handler. + +```go import ( "go.elastic.co/apm/module/apmgin/v2" ) @@ -168,19 +155,18 @@ func main() { engine.Use(apmgin.Middleware(engine)) ... } ----- +``` The apmgin middleware will recover panics and send them to Elastic APM, so you do not need to install the gin.Recovery middleware. -[[builtin-modules-apmfiber]] -==== module/apmfiber -Package apmfiber provides middleware for the https://gofiber.io/[Fiber] web framework, versions 2.x (v2.18.0 and greater). -For each request, a transaction is stored in the request context, which can be obtained via -https://pkg.go.dev/github.com/gofiber/fiber/v2#Ctx[fiber.Ctx]`.Context()` in your handler. +## module/apmfiber [builtin-modules-apmfiber] + +Package apmfiber provides middleware for the [Fiber](https://gofiber.io/) web framework, versions 2.x (v2.18.0 and greater). -[source,go] ----- +For each request, a transaction is stored in the request context, which can be obtained via [fiber.Ctx](https://pkg.go.dev/github.com/gofiber/fiber/v2#Ctx)`.Context()` in your handler. + +```go import ( "go.elastic.co/apm/module/apmfiber/v2" ) @@ -190,23 +176,18 @@ func main() { app.Use(apmfiber.Middleware()) ... } ----- +``` + +The apmfiber middleware will recover panics and send them to Elastic APM, so you do not need to install the fiber [recover](https://docs.gofiber.io/api/middleware/recover) middleware. You can disable default behaviour by using `WithPanicPropagation` option. -The apmfiber middleware will recover panics and send them to Elastic APM, -so you do not need to install the fiber https://docs.gofiber.io/api/middleware/recover[recover] middleware. -You can disable default behaviour by using `WithPanicPropagation` option. +## module/apmbeego [builtin-modules-apmbeego] -[[builtin-modules-apmbeego]] -==== module/apmbeego -Package apmbeego provides middleware for the https://beego.me/[Beego] web framework. +Package apmbeego provides middleware for the [Beego](https://beego.me/) web framework. -For each request, a transaction is stored in the request context, which can be obtained via -https://godoc.org/github.com/astaxie/beego/context#Context[beego/context.Context]`.Request.Context()` -in your controller. +For each request, a transaction is stored in the request context, which can be obtained via [beego/context.Context](https://godoc.org/github.com/astaxie/beego/context#Context)`.Request.Context()` in your controller. -[source,go] ----- +```go import ( "github.com/astaxie/beego" @@ -227,17 +208,16 @@ func main() { beego.Router("/thing/:id:int", &thingController{}, "get:Get") beego.RunWithMiddleWares("localhost:8080", apmbeego.Middleware()) } ----- +``` -[[builtin-modules-apmgorilla]] -==== module/apmgorilla -Package apmgorilla provides middleware for the http://www.gorillatoolkit.org/pkg/mux[Gorilla Mux] router. -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request[http.Request]`.Context()` in your handler. +## module/apmgorilla [builtin-modules-apmgorilla] -[source,go] ----- +Package apmgorilla provides middleware for the [Gorilla Mux](http://www.gorillatoolkit.org/pkg/mux) router. + +For each request, a transaction is stored in the request context, which can be obtained via [http.Request](https://golang.org/pkg/net/http/#Request)`.Context()` in your handler. + +```go import ( "github.com/gorilla/mux" @@ -249,19 +229,16 @@ func main() { apmgorilla.Instrument(router) ... } ----- +``` The apmgorilla middleware will recover panics and send them to Elastic APM, so you do not need to install any other recovery middleware. -[[builtin-modules-apmgrpc]] -==== module/apmgrpc -Package apmgrpc provides server and client interceptors for https://github.com/grpc/grpc-go[gRPC-Go]. -Server interceptors report transactions for each incoming request, while client interceptors -report spans for each outgoing request. For each RPC served, a transaction is stored in the -context passed into the method. -[source,go] ----- +## module/apmgrpc [builtin-modules-apmgrpc] + +Package apmgrpc provides server and client interceptors for [gRPC-Go](https://github.com/grpc/grpc-go). Server interceptors report transactions for each incoming request, while client interceptors report spans for each outgoing request. For each RPC served, a transaction is stored in the context passed into the method. + +```go import ( "go.elastic.co/apm/module/apmgrpc/v2" ) @@ -278,38 +255,27 @@ func main() { ) ... } ----- +``` -The server interceptor can optionally be made to recover panics, in the same way as -https://github.com/grpc-ecosystem/go-grpc-middleware/tree/master/recovery[grpc_recovery]. -The apmgrpc server interceptor will always send panics it observes as errors to the Elastic APM server. -If you want to recover panics but also want to continue using grpc_recovery, then you should ensure -that it comes before the apmgrpc interceptor in the interceptor chain, or panics will not be captured -by apmgrpc. +The server interceptor can optionally be made to recover panics, in the same way as [grpc_recovery](https://github.com/grpc-ecosystem/go-grpc-middleware/tree/master/recovery). The apmgrpc server interceptor will always send panics it observes as errors to the Elastic APM server. If you want to recover panics but also want to continue using grpc_recovery, then you should ensure that it comes before the apmgrpc interceptor in the interceptor chain, or panics will not be captured by apmgrpc. -[source,go] ----- +```go server := grpc.NewServer(grpc.UnaryInterceptor( apmgrpc.NewUnaryServerInterceptor(apmgrpc.WithRecovery()), )) ... ----- +``` + +Stream interceptors emit transactions and spans that represent the entire stream, and not individual messages. For client streams, spans will be ended when the request fails; when any of `grpc.ClientStream.RecvMsg`, `grpc.ClientStream.SendMsg`, or `grpc.ClientStream.Header` return with an error; or when `grpc.ClientStream.RecvMsg` returns for a non-streaming server method. -Stream interceptors emit transactions and spans that represent the entire stream, -and not individual messages. For client streams, spans will be ended when the request -fails; when any of `grpc.ClientStream.RecvMsg`, `grpc.ClientStream.SendMsg`, or -`grpc.ClientStream.Header` return with an error; or when `grpc.ClientStream.RecvMsg` -returns for a non-streaming server method. -[[builtin-modules-apmhttprouter]] -==== module/apmhttprouter -Package apmhttprouter provides a low-level middleware handler for https://github.com/julienschmidt/httprouter[httprouter]. +## module/apmhttprouter [builtin-modules-apmhttprouter] -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request[http.Request]`.Context()` in your handler. +Package apmhttprouter provides a low-level middleware handler for [httprouter](https://github.com/julienschmidt/httprouter). -[source,go] ----- +For each request, a transaction is stored in the request context, which can be obtained via [http.Request](https://golang.org/pkg/net/http/#Request)`.Context()` in your handler. + +```go import ( "github.com/julienschmidt/httprouter" @@ -323,16 +289,13 @@ func main() { router.GET(route, apmhttprouter.Wrap(h, route)) ... } ----- +``` -https://github.com/julienschmidt/httprouter/pull/139[httprouter does not provide a means of obtaining the matched route], hence the route must be passed into the wrapper. +[httprouter does not provide a means of obtaining the matched route](https://github.com/julienschmidt/httprouter/pull/139), hence the route must be passed into the wrapper. -Alternatively, use the `apmhttprouter.Router` type, which wraps `httprouter.Router`, -providing the same API and instrumenting added routes. To use this wrapper type, rewrite your use of `httprouter.New` to `apmhttprouter.New`; the returned type -is `*apmhttprouter.Router`, and not `*httprouter.Router`. +Alternatively, use the `apmhttprouter.Router` type, which wraps `httprouter.Router`, providing the same API and instrumenting added routes. To use this wrapper type, rewrite your use of `httprouter.New` to `apmhttprouter.New`; the returned type is `*apmhttprouter.Router`, and not `*httprouter.Router`. -[source,go] ----- +```go import "go.elastic.co/apm/module/apmhttprouter/v2" func main() { @@ -341,18 +304,16 @@ func main() { router.GET(route, h) ... } ----- +``` + -[[builtin-modules-apmnegroni]] -==== module/apmnegroni +## module/apmnegroni [builtin-modules-apmnegroni] -Package apmnegroni provides middleware for the https://github.com/urfave/negroni/[negroni] library. +Package apmnegroni provides middleware for the [negroni](https://github.com/urfave/negroni/) library. -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request.Context[http.Request.Context] in your handler. +For each request, a transaction is stored in the request context, which can be obtained via [http.Request.Context](https://golang.org/pkg/net/http/#Request.Context) in your handler. -[source,go] ----- +```go import ( "net/http" @@ -369,49 +330,46 @@ func main() { n.UseHandler(serverHandler) http.ListenAndServe(":8080", n) } ----- +``` The apmnegroni handler will recover panics and send them to Elastic APM. -[[builtin-modules-apmlambda]] -==== module/apmlambda + +## module/apmlambda [builtin-modules-apmlambda] + Package apmlambda intercepts requests to your AWS Lambda function invocations. -experimental[] +::::{warning} +This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. +:::: + Importing the package is enough to report the function invocations. -[source,go] ----- +```go import ( _ "go.elastic.co/apm/module/apmlambda/v2" ) ----- +``` + +We currently do not expose the transactions via context; when we do, it will be necessary to make a small change to your code to call apmlambda.Start instead of lambda.Start. + -We currently do not expose the transactions via context; when we do, it will be -necessary to make a small change to your code to call apmlambda.Start instead of -lambda.Start. +## module/apmsql [builtin-modules-apmsql] -[[builtin-modules-apmsql]] -==== module/apmsql -Package apmsql provides a means of wrapping `database/sql` drivers so that queries and other -executions are reported as spans within the current transaction. +Package apmsql provides a means of wrapping `database/sql` drivers so that queries and other executions are reported as spans within the current transaction. -To trace SQL queries, register drivers using apmsql.Register and obtain connections -with apmsql.Open. The parameters are exactly the same as if you were to call sql.Register -and sql.Open respectively. +To trace SQL queries, register drivers using apmsql.Register and obtain connections with apmsql.Open. The parameters are exactly the same as if you were to call sql.Register and sql.Open respectively. -As a convenience, we also provide packages which will automatically register popular drivers -with apmsql.Register: +As a convenience, we also provide packages which will automatically register popular drivers with apmsql.Register: -- module/apmsql/pq (github.com/lib/pq) -- module/apmsql/pgxv4 (github.com/jackc/pgx/v4/stdlib) -- module/apmsql/mysql (github.com/go-sql-driver/mysql) -- module/apmsql/sqlite3 (github.com/mattn/go-sqlite3) -- module/apmsql/sqlserver (github.com/microsoft/mssqldb) +* module/apmsql/pq (github.com/lib/pq) +* module/apmsql/pgxv4 (github.com/jackc/pgx/v4/stdlib) +* module/apmsql/mysql (github.com/go-sql-driver/mysql) +* module/apmsql/sqlite3 (github.com/mattn/go-sqlite3) +* module/apmsql/sqlserver (github.com/microsoft/mssqldb) -[source,go] ----- +```go import ( "go.elastic.co/apm/module/apmsql/v2" _ "go.elastic.co/apm/module/apmsql/v2/pq" @@ -422,20 +380,18 @@ func main() { db, err := apmsql.Open("postgres", "postgres://...") db, err := apmsql.Open("sqlite3", ":memory:") } ----- +``` + +Spans will be created for queries and other statement executions if the context methods are used, and the context includes a transaction. + -Spans will be created for queries and other statement executions if the context methods are -used, and the context includes a transaction. +## module/apmgopg [builtin-modules-apmgopg] -[[builtin-modules-apmgopg]] -==== module/apmgopg -Package apmgopg provides a means of instrumenting http://github.com/go-pg/pg[go-pg] database operations. +Package apmgopg provides a means of instrumenting [go-pg](http://github.com/go-pg/pg) database operations. -To trace `go-pg` statements, call `apmgopg.Instrument` with the database instance you plan on using and provide -a context that contains an apm transaction. +To trace `go-pg` statements, call `apmgopg.Instrument` with the database instance you plan on using and provide a context that contains an apm transaction. -[source,go] ----- +```go import ( "github.com/go-pg/pg" @@ -448,19 +404,18 @@ func main() { db.WithContext(ctx).Model(...) } ----- -Spans will be created for queries and other statement executions if the context methods are -used, and the context includes a transaction. +``` -[[builtin-modules-apmgopgv10]] -==== module/apmgopgv10 -Package apmgopgv10 provides a means of instrumenting v10 of http://github.com/go-pg/pg[go-pg] database operations. +Spans will be created for queries and other statement executions if the context methods are used, and the context includes a transaction. -To trace `go-pg` statements, call `apmgopgv10.Instrument` with the database instance you plan on using and provide -a context that contains an apm transaction. -[source,go] ----- +## module/apmgopgv10 [builtin-modules-apmgopgv10] + +Package apmgopgv10 provides a means of instrumenting v10 of [go-pg](http://github.com/go-pg/pg) database operations. + +To trace `go-pg` statements, call `apmgopgv10.Instrument` with the database instance you plan on using and provide a context that contains an apm transaction. + +```go import ( "github.com/go-pg/pg/v10" @@ -473,21 +428,18 @@ func main() { db.WithContext(ctx).Model(...) } ----- +``` + -[[builtin-modules-apmgorm]] -==== module/apmgorm -Package apmgorm provides a means of instrumenting http://gorm.io[GORM] database operations. +## module/apmgorm [builtin-modules-apmgorm] -To trace `GORM` operations, import the appropriate `apmgorm/dialects` package (instead of the -`gorm/dialects` package), and use `apmgorm.Open` (instead of `gorm.Open`). The parameters are -exactly the same. +Package apmgorm provides a means of instrumenting [GORM](http://gorm.io) database operations. -Once you have a `*gorm.DB` from `apmgorm.Open`, you can call `apmgorm.WithContext` to -propagate a context containing a transaction to the operations: +To trace `GORM` operations, import the appropriate `apmgorm/dialects` package (instead of the `gorm/dialects` package), and use `apmgorm.Open` (instead of `gorm.Open`). The parameters are exactly the same. -[source,go] ----- +Once you have a `*gorm.DB` from `apmgorm.Open`, you can call `apmgorm.WithContext` to propagate a context containing a transaction to the operations: + +```go import ( "go.elastic.co/apm/module/apmgorm/v2" _ "go.elastic.co/apm/module/apmgorm/v2/dialects/postgres" @@ -499,19 +451,18 @@ func main() { db = apmgorm.WithContext(ctx, db) db.Find(...) // creates a "SELECT FROM " span } ----- +``` + + +## module/apmgormv2 [_moduleapmgormv2] -==== module/apmgormv2 -Package apmgormv2 provides a means of instrumenting http://gorm.io[GORM] database operations. +Package apmgormv2 provides a means of instrumenting [GORM](http://gorm.io) database operations. -To trace `GORM` operations, import the appropriate `apmgormv2/driver` package (instead of the -`gorm.io/driver` package), use these dialects to `gorm.Open` instead of gorm drivers. +To trace `GORM` operations, import the appropriate `apmgormv2/driver` package (instead of the `gorm.io/driver` package), use these dialects to `gorm.Open` instead of gorm drivers. -Once you have a `*gorm.DB`, you can call `db.WithContext` to -propagate a context containing a transaction to the operations: +Once you have a `*gorm.DB`, you can call `db.WithContext` to propagate a context containing a transaction to the operations: -[source,go] ----- +```go import ( "gorm.io/gorm" postgres "go.elastic.co/apm/module/apmgormv2/v2/driver/postgres" @@ -523,22 +474,18 @@ func main() { db = db.WithContext(ctx) db.Find(...) // creates a "SELECT FROM " span } ----- +``` + + +## module/apmgocql [builtin-modules-apmgocql] -[[builtin-modules-apmgocql]] -==== module/apmgocql -Package apmgocql provides a means of instrumenting https://github.com/gocql/gocql[gocql] so -that queries are reported as spans within the current transaction. +Package apmgocql provides a means of instrumenting [gocql](https://github.com/gocql/gocql) so that queries are reported as spans within the current transaction. -To report `gocql` queries, construct an `apmgocql.Observer` and assign it to -the `QueryObserver` and `BatchObserver` fields of `gocql.ClusterConfig`, or install it -into a specific `gocql.Query` or `gocql.Batch` via their `Observer` methods. +To report `gocql` queries, construct an `apmgocql.Observer` and assign it to the `QueryObserver` and `BatchObserver` fields of `gocql.ClusterConfig`, or install it into a specific `gocql.Query` or `gocql.Batch` via their `Observer` methods. -Spans will be created for queries as long as they have context associated, and the -context includes a transaction. +Spans will be created for queries as long as they have context associated, and the context includes a transaction. -[source,go] ----- +```go import ( "github.com/gocql/gocql" @@ -556,27 +503,18 @@ func main() { err = session.Query("SELECT * FROM foo").WithContext(ctx).Exec() ... } ----- - -[[builtin-modules-apmredigo]] -==== module/apmredigo -Package apmredigo provides a means of instrumenting https://github.com/gomodule/redigo[Redigo] -so that Redis commands are reported as spans within the current transaction. - -To report Redis commands, use the top-level `Do` or `DoWithTimeout` functions. -These functions have the same signature as the `redis.Conn` equivalents apart from an -initial `context.Context` parameter. If the context passed in contains a sampled -transaction, a span will be reported for the Redis command. - -Another top-level function, `Wrap`, is provided to wrap a `redis.Conn` such that its -`Do` and `DoWithTimeout` methods call the above mentioned functions. Initially, the -wrapped connection will be associated with the background context; its `WithContext` -method may be used to obtain a shallow copy with another context. For example, in an -HTTP middleware you might bind a connection to the request context, which would -associate spans with the request's APM transaction. - -[source,go] ----- +``` + + +## module/apmredigo [builtin-modules-apmredigo] + +Package apmredigo provides a means of instrumenting [Redigo](https://github.com/gomodule/redigo) so that Redis commands are reported as spans within the current transaction. + +To report Redis commands, use the top-level `Do` or `DoWithTimeout` functions. These functions have the same signature as the `redis.Conn` equivalents apart from an initial `context.Context` parameter. If the context passed in contains a sampled transaction, a span will be reported for the Redis command. + +Another top-level function, `Wrap`, is provided to wrap a `redis.Conn` such that its `Do` and `DoWithTimeout` methods call the above mentioned functions. Initially, the wrapped connection will be associated with the background context; its `WithContext` method may be used to obtain a shallow copy with another context. For example, in an HTTP middleware you might bind a connection to the request context, which would associate spans with the request’s APM transaction. + +```go import ( "net/http" @@ -596,22 +534,16 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { defer conn.Close() ... } ----- - -[[builtin-modules-apmgoredis]] -==== module/apmgoredis -Package apmgoredis provides a means of instrumenting https://github.com/go-redis/redis[go-redis/redis] -so that Redis commands are reported as spans within the current transaction. - -To report Redis commands, use the top-level `Wrap` function to wrap a -`redis.Client`, `redis.ClusterClient`, or `redis.Ring`. Initially, the wrapped -client will be associated with the background context; its `WithContext` method -may be used to obtain a shallow copy with another context. For example, in an -HTTP middleware you might bind a client to the request context, which would -associate spans with the request's APM transaction. - -[source,go] ----- +``` + + +## module/apmgoredis [builtin-modules-apmgoredis] + +Package apmgoredis provides a means of instrumenting [go-redis/redis](https://github.com/go-redis/redis) so that Redis commands are reported as spans within the current transaction. + +To report Redis commands, use the top-level `Wrap` function to wrap a `redis.Client`, `redis.ClusterClient`, or `redis.Ring`. Initially, the wrapped client will be associated with the background context; its `WithContext` method may be used to obtain a shallow copy with another context. For example, in an HTTP middleware you might bind a client to the request context, which would associate spans with the request’s APM transaction. + +```go import ( "net/http" @@ -630,18 +562,16 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { client := apmgoredis.Wrap(redisClient).WithContext(req.Context()) ... } ----- +``` + + +## module/apmgoredisv8 [builtin-modules-apmgoredisv8] -[[builtin-modules-apmgoredisv8]] -==== module/apmgoredisv8 -Package apmgoredisv8 provides a means of instrumenting https://github.com/go-redis/redis[go-redis/redis] for v8 -so that Redis commands are reported as spans within the current transaction. +Package apmgoredisv8 provides a means of instrumenting [go-redis/redis](https://github.com/go-redis/redis) for v8 so that Redis commands are reported as spans within the current transaction. -To report Redis commands, you can call `AddHook(apmgoredis.NewHook())` -from instance of `redis.Client`, `redis.ClusterClient`, or `redis.Ring`. +To report Redis commands, you can call `AddHook(apmgoredis.NewHook())` from instance of `redis.Client`, `redis.ClusterClient`, or `redis.Ring`. -[source,go] ----- +```go import ( "github.com/go-redis/redis/v8" @@ -656,18 +586,16 @@ func main() { redisClient.Get(ctx, "key") } ----- +``` -[[builtin-modules-apmrestful]] -==== module/apmrestful -Package apmrestful provides a https://github.com/emicklei/go-restful[go-restful] filter -for tracing requests, and capturing panics. -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request[http.Request]`.Context()` in your handler. +## module/apmrestful [builtin-modules-apmrestful] -[source,go] ----- +Package apmrestful provides a [go-restful](https://github.com/emicklei/go-restful) filter for tracing requests, and capturing panics. + +For each request, a transaction is stored in the request context, which can be obtained via [http.Request](https://golang.org/pkg/net/http/#Request)`.Context()` in your handler. + +```go import ( "github.com/emicklei/go-restful" @@ -687,18 +615,16 @@ func main() { })) ... } ----- +``` + -[[builtin-modules-apmchi]] -==== module/apmchi -Package apmchi provides middleware for https://github.com/go-chi/chi[chi] routers, -for tracing requests and capturing panics. +## module/apmchi [builtin-modules-apmchi] -For each request, a transaction is stored in the request context, which can be obtained via -https://golang.org/pkg/net/http/#Request[http.Request]`.Context()` in your handler. +Package apmchi provides middleware for [chi](https://github.com/go-chi/chi) routers, for tracing requests and capturing panics. -[source,go] ----- +For each request, a transaction is stored in the request context, which can be obtained via [http.Request](https://golang.org/pkg/net/http/#Request)`.Context()` in your handler. + +```go import ( "github.com/go-chi/chi" @@ -711,16 +637,14 @@ func main() { r.Get("/route/{pattern}", routeHandler) ... } ----- +``` + -[[builtin-modules-apmlogrus]] -==== module/apmlogrus -Package apmlogrus provides a https://github.com/sirupsen/logrus[logrus] Hook -implementation for sending error messages to Elastic APM, as well as a function -for adding trace context fields to log records. +## module/apmlogrus [builtin-modules-apmlogrus] -[source,go] ----- +Package apmlogrus provides a [logrus](https://github.com/sirupsen/logrus) Hook implementation for sending error messages to Elastic APM, as well as a function for adding trace context fields to log records. + +```go import ( "github.com/sirupsen/logrus" @@ -741,16 +665,14 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { // Output: // {"level":"debug","msg":"handling request","time":"1970-01-01T00:00:00Z","trace.id":"67829ae467e896fb2b87ec2de50f6c0e","transaction.id":"67829ae467e896fb"} } ----- +``` + -[[builtin-modules-apmzap]] -==== module/apmzap -Package apmzap provides a https://godoc.org/go.uber.org/zap/zapcore#Core[go.uber.org/zap/zapcore.Core] -implementation for sending error messages to Elastic APM, as well as a function -for adding trace context fields to log records. +## module/apmzap [builtin-modules-apmzap] -[source,go] ----- +Package apmzap provides a [go.uber.org/zap/zapcore.Core](https://godoc.org/go.uber.org/zap/zapcore#Core) implementation for sending error messages to Elastic APM, as well as a function for adding trace context fields to log records. + +```go import ( "go.uber.org/zap" @@ -774,17 +696,14 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { // Output: // {"level":"debug","msg":"handling request","trace.id":"67829ae467e896fb2b87ec2de50f6c0e","transaction.id":"67829ae467e896fb"} } ----- +``` + -[[builtin-modules-apmslog]] -==== module/apmslog -Package apmslog provides a https://pkg.go.dev/log/slog[slog] Handler -implementation for sending error messages to Elastic APM, as well as automatically -attaching trace context fields to log records while using the context aware -logging methods. +## module/apmslog [builtin-modules-apmslog] -[source,go] ----- +Package apmslog provides a [slog](https://pkg.go.dev/log/slog) Handler implementation for sending error messages to Elastic APM, as well as automatically attaching trace context fields to log records while using the context aware logging methods. + +```go import ( "context" "log/slog" @@ -826,16 +745,14 @@ func ExampleHandler() { // BOTH errors with the log msg will be reported to apm. [ error, err ] slog attribute keys are by default reported logger.ErrorContext(ctx, "I will report this error to apm", "error", errors.New("new error"), "err", errors.New("new err")) } ----- +``` + + +## module/apmzerolog [builtin-modules-apmzerolog] -[[builtin-modules-apmzerolog]] -==== module/apmzerolog -Package apmzerolog provides an implementation of https://github.com/rs/zerolog[Zerolog]'s -`LevelWriter` interface for sending error records to Elastic APM, as well as functions -for adding trace context and detailed error stack traces to log records. +Package apmzerolog provides an implementation of [Zerolog](https://github.com/rs/zerolog)'s `LevelWriter` interface for sending error records to Elastic APM, as well as functions for adding trace context and detailed error stack traces to log records. -[source,go] ----- +```go import ( "net/http" @@ -865,21 +782,16 @@ func traceLoggingMiddleware(h http.Handler) http.Handler { h.ServeHTTP(w, req) }) } ----- +``` + + +## module/apmelasticsearch [builtin-modules-apmelasticsearch] -[[builtin-modules-apmelasticsearch]] -==== module/apmelasticsearch -Package apmelasticsearch provides a means of instrumenting the HTTP transport -of Elasticsearch clients, such as https://github.com/elastic/go-elasticsearch[go-elasticsearch] -and https://github.com/olivere/elastic[olivere/elastic], so that Elasticsearch -requests are reported as spans within the current transaction. +Package apmelasticsearch provides a means of instrumenting the HTTP transport of Elasticsearch clients, such as [go-elasticsearch](https://github.com/elastic/go-elasticsearch) and [olivere/elastic](https://github.com/olivere/elastic), so that Elasticsearch requests are reported as spans within the current transaction. -To create spans for an Elasticsearch request, wrap the client's HTTP -transport using the `WrapRoundTripper` function, and then associate the request -with a context containing a transaction. +To create spans for an Elasticsearch request, wrap the client’s HTTP transport using the `WrapRoundTripper` function, and then associate the request with a context containing a transaction. -[source,go] ----- +```go import ( "net/http" @@ -896,20 +808,16 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { result, err := client.Search("index").Query(elastic.NewMatchAllQuery()).Do(req.Context()) ... } ----- +``` -[[builtin-modules-apmmongo]] -==== module/apmmongo -Package apmmongo provides a means of instrumenting the -https://github.com/mongodb/mongo-go-driver[MongoDB Go Driver], so that MongoDB -commands are reported as spans within the current transaction. -To create spans for MongoDB commands, pass in a `CommandMonitor` created -with `apmmongo.CommandMonitor` as an option when constructing a client, and then when -executing commands, pass in a context containing a transaction. +## module/apmmongo [builtin-modules-apmmongo] -[source,go] ----- +Package apmmongo provides a means of instrumenting the [MongoDB Go Driver](https://github.com/mongodb/mongo-go-driver), so that MongoDB commands are reported as spans within the current transaction. + +To create spans for MongoDB commands, pass in a `CommandMonitor` created with `apmmongo.CommandMonitor` as an option when constructing a client, and then when executing commands, pass in a context containing a transaction. + +```go import ( "context" "net/http" @@ -931,30 +839,25 @@ func handleRequest(w http.ResponseWriter, req *http.Request) { cur, err := collection.Find(req.Context(), bson.D{}) ... } ----- +``` + + +## module/apmawssdkgo [builtin-modules-apmawssdkgo] -[[builtin-modules-apmawssdkgo]] -==== module/apmawssdkgo -Package apmawssdkgo provides a means of instrumenting the -https://github.com/aws/aws-sdk-go[AWS SDK Go] session object, so that -AWS requests are reported as spans within the current transaction. +Package apmawssdkgo provides a means of instrumenting the [AWS SDK Go](https://github.com/aws/aws-sdk-go) session object, so that AWS requests are reported as spans within the current transaction. -To create spans for AWS requests, you should wrap the `session.Session` created -with `session.NewSession` when constructing a client. When executing commands, -pass in a context containing a transaction. +To create spans for AWS requests, you should wrap the `session.Session` created with `session.NewSession` when constructing a client. When executing commands, pass in a context containing a transaction. The following services are supported: -- S3 -- DynamoDB -- SQS -- SNS +* S3 +* DynamoDB +* SQS +* SNS -Passing a `session.Session` wrapped with `apmawssdkgo.WrapSession` to these -services from the AWS SDK will report spans within the current transaction. +Passing a `session.Session` wrapped with `apmawssdkgo.WrapSession` to these services from the AWS SDK will report spans within the current transaction. -[source,go] ----- +```go import ( "context" "net/http" @@ -984,28 +887,22 @@ func (s *server) handleRequest(w http.ResponseWriter, req *http.Request) { }) ... } ----- +``` -[[builtin-modules-apmazure]] -==== module/apmazure -Package apmazure provides a means of instrumenting the -https://github.com/Azure/azure-pipeline-go[Azure Pipeline Go] pipeline object, -so that Azure requests are reported as spans within the current transaction. -To create spans for Azure requests, you should create a new pipeline using the -relevant service's `NewPipeline` function, like `azblob.NewPipeline`, then wrap -the `pipeline.Pipeline` with `apmazure.WrapPipeline`. The returned `Pipeline` -can be used as normal. +## module/apmazure [builtin-modules-apmazure] -The following services are supported: +Package apmazure provides a means of instrumenting the [Azure Pipeline Go](https://github.com/Azure/azure-pipeline-go) pipeline object, so that Azure requests are reported as spans within the current transaction. + +To create spans for Azure requests, you should create a new pipeline using the relevant service’s `NewPipeline` function, like `azblob.NewPipeline`, then wrap the `pipeline.Pipeline` with `apmazure.WrapPipeline`. The returned `Pipeline` can be used as normal. -- Blob Storage -- Queue Storage -- File Storage +The following services are supported: +* Blob Storage +* Queue Storage +* File Storage -[source,go] ----- +```go import ( "github.com/Azure/azure-storage-blob-go/azblob" @@ -1022,25 +919,20 @@ func main() { // Use the blobURL to interact with Blob Storage ... } ----- +``` + + +## module/apmpgx [builtin-modules-apmpgx] -[[builtin-modules-apmpgx]] -==== module/apmpgx -Package apmpgx provides a means of instrumenting the -https://github.com/jackc/pgx[Pgx] for v4.17+, -so that SQL queries are reported as spans within the current transaction. -Also this lib have extended support of pgx, such as COPY FROM queries and BATCH which have their own span types: -`db.postgresql.copy` and `db.postgresql.batch` accordingly. +Package apmpgx provides a means of instrumenting the [Pgx](https://github.com/jackc/pgx) for v4.17+, so that SQL queries are reported as spans within the current transaction. Also this lib have extended support of pgx, such as COPY FROM queries and BATCH which have their own span types: `db.postgresql.copy` and `db.postgresql.batch` accordingly. -To report `pgx` queries, create `pgx` connection, and then provide config to `apmpgx.Instrument()`. If logger is presented in config, -then traces will be written to log. (It's safe to use without logger) +To report `pgx` queries, create `pgx` connection, and then provide config to `apmpgx.Instrument()`. If logger is presented in config, then traces will be written to log. (It’s safe to use without logger) -Spans will be created for queries as long as they have context associated, and the -context includes a transaction. +Spans will be created for queries as long as they have context associated, and the context includes a transaction. Example with pool: -[source,go] ----- + +```go import ( "github.com/jackc/pgx/v4/pgxpool" @@ -1056,11 +948,11 @@ func main() { apmpgx.Instrument(pool.ConnConfig) ... } ----- +``` Example without pool: -[source,go] ----- + +```go import ( "github.com/jackc/pgx/v4" @@ -1074,4 +966,6 @@ func main() { apmpgx.Instrument(c.Config()) ... } ----- +``` + + diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md new file mode 100644 index 000000000..e47550b2a --- /dev/null +++ b/docs/reference/configuration.md @@ -0,0 +1,571 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/configuration.html +--- + +# Configuration [configuration] + +Adapt the Elastic APM Go agent to your needs with one of the following methods—​listed in descending order of precedence: + +1. [APM Agent Configuration via Kibana](docs-content://solutions/observability/apps/apm-agent-central-configuration.md) (supported options are marked with [![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration)) +2. In code, using the [Tracer Config API](/reference/api-documentation.md#tracer-config-api) +3. Environment variables + +Configuration defined via Kibana will take precedence over the same configuration defined in code, which takes precedence over environment variables. If configuration is defined via Kibana, and then that is later removed, the agent will revert to configuration defined locally via either the Tracer Config API or environment variables. + +To simplify development and testing, the agent defaults to sending data to the Elastic APM Server at `http://localhost:8200`. To send data to an alternative location, you must configure [ELASTIC_APM_SERVER_URL](#config-server-url). Depending on the configuration of your server, you may also need to set [ELASTIC_APM_API_KEY](#config-api-key), [ELASTIC_APM_SECRET_TOKEN](#config-secret-token), and [ELASTIC_APM_VERIFY_SERVER_CERT](#config-verify-server-cert). All other variables have usable defaults. + + +## Dynamic configuration [dynamic-configuration] + +Configuration options marked with the ![dynamic config](../images/dynamic-config.svg "") badge can be changed at runtime when set from a supported source. + +The Go Agent supports [Central configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with [`ELASTIC_APM_CENTRAL_CONFIG`](#config-central-config). + + +## Configuration formats [_configuration_formats] + +Some options require a unit, either duration or size. These need to be provided in a specific format. + + +### Duration format [_duration_format] + +The *duration* format is used for options like timeouts. The unit is provided as a suffix directly after the number, without any whitespace. + +**Example:** `5ms` + +**Supported units:** + +* `ms` (milliseconds) +* `s` (seconds) +* `m` (minutes) + + +### Size format [_size_format] + +The *size* format is used for options such as maximum buffer sizes. The unit is provided as a suffix directly after the number, without any whitespace. + +**Example:** `10KB` + +**Supported units:** + +* B (bytes) +* KB (kilobytes) +* MB (megabytes) +* GB (gigabytes) + +::::{note} +We use the power-of-two sizing convention, e.g. 1KB = 1024B. +:::: + + + +## `ELASTIC_APM_SERVER_URL` [config-server-url] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SERVER_URL` | `http://localhost:8200` | `http://localhost:8200` | + +The URL for your Elastic APM Server. The Server supports both HTTP and HTTPS. If you use HTTPS, then you may need to configure your client machines so that the server certificate can be verified. You can disable certificate verification with [`ELASTIC_APM_VERIFY_SERVER_CERT`](#config-verify-server-cert). + + +## `ELASTIC_APM_SERVER_TIMEOUT` [config-server-timeout] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SERVER_TIMEOUT` | `30s` | `30s` | + +The timeout for requests made to your Elastic APM server. When set to zero or a negative value, timeouts will be disabled. + + +## `ELASTIC_APM_SECRET_TOKEN` [config-secret-token] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SECRET_TOKEN` | | "A random string" | + +This string is used to ensure that only your agents can send data to your APM server. Both the agents and the APM server have to be configured with the same secret token. + +::::{warning} +The secret token is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your secret token could be observed by an attacker. +:::: + + + +## `ELASTIC_APM_API_KEY` [config-api-key] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_API_KEY` | | "A base64-encoded string" | + +This base64-encoded string is used to ensure that only your agents can send data to your APM server. The API key must be created using the APM Server [command line tool](docs-content://solutions/observability/apps/api-keys.md). + +::::{warning} +The API Key is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker. +:::: + + + +## `ELASTIC_APM_SERVICE_NAME` [config-service-name] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SERVICE_NAME` | Executable name | `my-app` | + +The name of your service or application. This is used to keep all the errors and transactions of your service together and is the primary filter in the Elastic APM user interface. + +If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the executable name. e.g. if your executable is called "my-app.exe", then your service will be identified as "my-app". + +::::{note} +The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`. In other words: your service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores, and spaces. +:::: + + + +## `ELASTIC_APM_SERVICE_VERSION` [config-service-version] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SERVICE_VERSION` | | A string indicating the version of the deployed service | + +A version string for the currently deployed version of the service. If you don’t version your deployments, the recommended value for this field is the commit identifier of the deployed revision, e.g. the output of `git rev-parse HEAD`. + + +## `ELASTIC_APM_SERVICE_NODE_NAME` [config-service-node-name] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SERVICE_NODE_NAME` | | `my-node-name` | + +Optional name used to differentiate between nodes in a service. Must be unique, otherwise data from multiple nodes will be aggregated together. + +If you do not specify `ELASTIC_APM_SERVICE_NODE_NAME`, service nodes will be identified using the container ID if available, otherwise the host name. + +::::{note} +This feature is fully supported in the APM Server versions >= 7.5. +:::: + + + +## `ELASTIC_APM_ENVIRONMENT` [config-environment] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_ENVIRONMENT` | | `"production"` | + +The name of the environment this service is deployed in, e.g. "production" or "staging". + +Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See [environment selector](docs-content://solutions/observability/apps/filter-application-data.md#apm-filter-your-data-service-environment-filter) in the APM app for more information. + +::::{note} +This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2. +:::: + + + +## `ELASTIC_APM_ACTIVE` [config-active] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_ACTIVE` | true | `false` | + +Enable or disable the agent. If set to false, then the Go agent does not send any data to the Elastic APM server, and instrumentation overhead is minimized. + + +## `ELASTIC_APM_RECORDING` [config-recording] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_RECORDING` | true | `false` | + +Enable or disable recording of events. If set to false, then the Go agent does not send any events to the Elastic APM server, and instrumentation overhead is minimized, but the agent will continue to poll the server for configuration changes. + + +## `ELASTIC_APM_GLOBAL_LABELS` [config-global-labels] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_GLOBAL_LABELS` | | `dept=engineering,rack=number8` | + +Labels are added to all events. The format for labels is: `key=value[,key=value[,...]]`. Any labels set by application via the API will override global labels with the same keys. + +This option requires APM Server 7.2 or greater, and will have no effect when using older server versions. + + +## `ELASTIC_APM_TRANSACTION_IGNORE_URLS` [config-ignore-urls] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` | | `/heartbeat*, *.jpg` | + +A list of patterns to match HTTP requests to ignore. An incoming HTTP request whose request line matches any of the patterns will not be reported as a transaction. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. Prefixing a pattern with `(?-i)` makes the matching case sensitive. + +::::{note} +This configuration was previously known as `ELASTIC_APM_IGNORE_URLS`, which has been deprecated and will be removed in a future major version of the agent. +:::: + + + +## `ELASTIC_APM_SANITIZE_FIELD_NAMES` [config-sanitize-field-names] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `password, passwd, pwd, secret, *key, *token*, *session*, *credit*, *card*, *auth*, set-cookie, *principal*` | `sekrits` | + +A list of patterns to match the names of HTTP headers, cookies, and POST form fields to redact. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. Prefixing a pattern with `(?-i)` makes the matching case sensitive. + + +## `ELASTIC_APM_CAPTURE_HEADERS` [config-capture-headers] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_CAPTURE_HEADERS` | `true` | + +For transactions that are HTTP requests, the Go agent can optionally capture request and response headers. + +Possible values: `true`, `false`. + +Captured headers are subject to sanitization, per [`ELASTIC_APM_SANITIZE_FIELD_NAMES`](#config-sanitize-field-names). + + +## `ELASTIC_APM_CAPTURE_BODY` [config-capture-body] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_CAPTURE_BODY` | `off` | + +For transactions that are HTTP requests, the Go agent can optionally capture the request body. + +Possible values: `errors`, `transactions`, `all`, `off`. + +::::{warning} +Request bodies often contain sensitive values like passwords, credit card numbers, and so on. If your service handles data like this, enable this feature with care. +:::: + + + +## `ELASTIC_APM_HOSTNAME` [config-hostname] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_HOSTNAME` | `os.Hostname()` | `app-server01` | + +The host name to use when sending error and transaction data to the APM server. + + +## `ELASTIC_APM_API_REQUEST_TIME` [config-api-request-time] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_API_REQUEST_TIME` | `10s` | + +The amount of time to wait before ending a request to the Elastic APM server. When you report transactions, spans and errors, the agent will initiate a request and send them to the server when there is enough data to send; the request will remain open until this time has been exceeded, or until the [maximum request size](#config-api-request-size) has been reached. + + +## `ELASTIC_APM_API_REQUEST_SIZE` [config-api-request-size] + +| Environment | Default | Minimum | Maximum | +| --- | --- | --- | --- | +| `ELASTIC_APM_API_REQUEST_SIZE` | `750KB` | `1KB` | `5MB` | + +The maximum size of request bodies to send to the Elastic APM server. The agent will maintain an in-memory buffer of compressed data for streaming to the APM server. + + +## `ELASTIC_APM_API_BUFFER_SIZE` [config-api-buffer-size] + +| Environment | Default | Minimum | Maximum | +| --- | --- | --- | --- | +| `ELASTIC_APM_API_BUFFER_SIZE` | `1MB` | `10KB` | `100MB` | + +The maximum number of bytes of uncompressed, encoded events to store in memory while the agent is busy. When the agent is able to, it will transfer buffered data to the request buffer, and start streaming it to the server. If the buffer fills up, new events will start replacing older ones. + + +## `ELASTIC_APM_TRANSACTION_MAX_SPANS` [config-transaction-max-spans] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `500` | + +Limits the amount of spans that are recorded per transaction. + +This is helpful in cases where a transaction creates a large number of spans (e.g. thousands of SQL queries). Setting an upper limit will prevent overloading the agent and the APM server with too much work for such edge cases. + + +## `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` [config-exit-span-min-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_EXIT_SPAN_MIN_DURATION` | `1ms` | + +Sets the minimum duration for an exit span to be reported. Spans shorter or equal to this threshold will be dropped by the agent and reported as statistics in the span’s transaction, as long as the transaction didn’t end before the span was reported. + +When span compression is enabled ([`ELASTIC_APM_SPAN_COMPRESSION_ENABLED`](#config-span-compression-enabled)), the sum of the compressed span composite is considered. + +The minimum duration allowed for this setting is 1 microsecond (`us`). + + +## `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` [config-span-frames-min-duration-ms] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `5ms` | + +The APM agent will collect a stack trace for every recorded span whose duration exceeds this configured value. While this is very helpful to find the exact place in your code that causes the span, collecting this stack trace does have some processing and storage overhead. + +::::{note} +This configuration has been deprecated and will be removed in a future major version of the agent. +:::: + + + +## `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` [config-span-stack-trace-min-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION` | `5ms` | + +The APM agent will collect a stack trace for every recorded span whose duration exceeds this configured value. While this is very helpful to find the exact place in your code that causes the span, collecting this stack trace does have some processing and storage overhead. + +::::{note} +This configuration was previously known as `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION`, which has been deprecated and will be removed in a future major version of the agent. +:::: + + + +## `ELASTIC_APM_STACK_TRACE_LIMIT` [config-stack-trace-limit] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_STACK_TRACE_LIMIT` | `50` | + +Limits the number of frames captured for each stack trace. + +Setting the limit to 0 will disable stack trace collection, while any positive integer value will be used as the maximum number of frames to collect. Setting a negative value, such as -1, means that all frames will be collected. + + +## `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` [config-transaction-sample-rate] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `1.0` | + +By default, the agent will sample every transaction (e.g. request to your service). To reduce overhead and storage requirements, set the sample rate to a value between `0.0` and `1.0`. We still record overall time and the result for unsampled transactions, but no context information, tags, or spans. + + +## `ELASTIC_APM_METRICS_INTERVAL` [config-metrics-interval] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_METRICS_INTERVAL` | 30s | + +The interval at which APM agent gathers and reports metrics. Set to `0s` to disable. + + +## `ELASTIC_APM_DISABLE_METRICS` [config-disable-metrics] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_DISABLE_METRICS` | | `system.*, *cpu*` | + +Disables the collection of certain metrics. If the name of a metric matches any of the wildcard expressions, it will not be collected. + +This option supports the wildcard `*`, which matches zero or more characters. Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default. Prefixing a pattern with `(?-i)` makes the matching case sensitive. + + +## `ELASTIC_APM_BREAKDOWN_METRICS` [config-breakdown-metrics] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_BREAKDOWN_METRICS` | `true` | + +Capture breakdown metrics. Set to `false` to disable. + + +## `ELASTIC_APM_SERVER_CERT` [config-server-cert] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SERVER_CERT` | | + +If you have configured your APM Server with a self signed TLS certificate, or you want to pin the server certificate, specify the path to the PEM-encoded certificate via the `ELASTIC_APM_SERVER_CERT` configuration. + + +## `ELASTIC_APM_SERVER_CA_CERT_FILE` [config-server-ca-cert-file] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SERVER_CA_CERT_FILE` | | + +The path to a PEM-encoded TLS Certificate Authority certificate that will be used for verifying the server’s TLS certificate chain. + + +## `ELASTIC_APM_VERIFY_SERVER_CERT` [config-verify-server-cert] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_VERIFY_SERVER_CERT` | `true` | + +By default, the agent verifies the server’s certificate if you use an HTTPS connection to the APM server. Verification can be disabled by changing this setting to `false`. This setting is ignored when `ELASTIC_APM_SERVER_CERT` is set. + + +## `ELASTIC_APM_LOG_FILE` [config-log-file] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_LOG_FILE` | | + +`ELASTIC_APM_LOG_FILE` specifies the output file for the agent’s default, internal logger. The file will be created, or truncated if it exists, when the process starts. By default, logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable it. This environment variable will be ignored if a logger is configured programatically. + +There are two special file names that the agent recognizes: `stdout` and `stderr`. These will configure the logger to write to standard output and standard error respectively. + + +## `ELASTIC_APM_LOG_LEVEL` [config-log-level] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_LOG_LEVEL` | `"error"` | + +`ELASTIC_APM_LOG_LEVEL` specifies the log level for the agent’s default, internal logger. The only two levels used by the logger are "error" and "debug". By default, logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable it. + +This environment variable will be ignored if a logger is configured programatically. + + +### `ELASTIC_APM_CENTRAL_CONFIG` [config-central-config] + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_CENTRAL_CONFIG` | `true` | + +Activate APM Agent central configuration via Kibana. By default the agent will poll the server for agent configuration changes. This can be disabled by changing the setting to `false`. See [APM Agent central configuration](docs-content://solutions/observability/apps/apm-agent-central-configuration.md) for more information. + +::::{note} +This feature requires APM Server v7.3 or later. +:::: + + + +### `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` [config-use-elastic-traceparent-header] + +| | | +| --- | --- | +| Environment | Default | +| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `true` | + +To enable [distributed tracing](docs-content://solutions/observability/apps/traces.md), the agent adds trace context headers to outgoing HTTP requests made with [module/apmhttp](/reference/builtin-modules.md#builtin-modules-apmhttp). These headers (`traceparent` and `tracestate`) are defined in the [W3C Trace Context](https://www.w3.org/TR/trace-context-1/) specification. + +When this setting is `true`, the agent will also add the header `elastic-apm-traceparent` for backwards compatibility with older versions of Elastic APM agents. + + +### `ELASTIC_APM_CLOUD_PROVIDER` [config-cloud-provider] + +| Environment | Default | Example | +| --- | --- | --- | +| `ELASTIC_APM_CLOUD_PROVIDER` | `"auto"` | `"aws"` | + +This config value allows you to specify which cloud provider should be assumed for metadata collection. By default, the agent will use trial and error to automatically collect the cloud metadata. + +Valid options are `"none"`, `"auto"`, `"aws"`, `"gcp"`, and `"azure"` If this config value is set to `"none"`, then no cloud metadata will be collected. + + +## `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` [config-span-compression-enabled] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_ENABLED` | `true` | + +When enabled, the agent will attempt to compress *short* exit spans that share the same parent into a composite span. The exact duration for what is considered *short*, depends on the compression strategy used (`same_kind` or `exact_match`). + +In order for a span to be compressible, these conditions need to be met: + +* Spans are exit spans. +* Spans are siblings (share the same parent). +* Spans have not propagated their context downstream. +* Each span duration is equal or lower to the compression strategy maximum duration. +* Spans are compressed with `same_kind` strategy when these attributes are equal: + + * `span.type`. + * `span.subtype`. + * `span.context.destination.service.resource` + +* Spans are compressed with `exact_match` strategy when all the previous conditions are met and the `span.name` is equal. + +Compressing short exit spans should provide some storage savings for services that create a lot of consecutive short exit spans to for example databases or cache services which are generally uninteresting when viewing a trace. + +::::{warning} +This feature is experimental and requires APM Server v7.15 or later. +:::: + + + +## `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` [config-span-compression-exact-match-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION` | `50ms` | + +The maximum duration to consider for compressing sibling exit spans that are an exact match for compression. + + +## `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` [config-span-compression-same-kind-duration] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION` | `0ms` | + +The maximum duration to consider for compressing sibling exit spans that are of the same kind for compression. + + +## `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` [config-trace-continuation-strategy] + +[![dynamic config](../images/dynamic-config.svg "") ](#dynamic-configuration) + +| Environment | Default | +| --- | --- | +| `ELASTIC_APM_TRACE_CONTINUATION_STRATEGY` | `continue` | + +This option allows some control over how the APM agent handles W3C trace-context headers on incoming requests. By default, the traceparent and tracestate headers are used per W3C spec for distributed tracing. However, in certain cases it can be helpful to not use the incoming traceparent header. Some example use cases: + +* An Elastic-monitored service is receiving requests with traceparent headers from unmonitored services. +* An Elastic-monitored service is publicly exposed, and does not want tracing data (trace-ids, sampling decisions) to possibly be spoofed by user requests. + +Valid options are `continue`, `restart`, and `restart_external`: + +continue +: The default behavior. An incoming `traceparent` value is used to continue the trace and determine the sampling decision. + +restart +: Always ignores the `traceparent` header of incoming requests. A new trace-id will be generated and the sampling decision will be made based on `transaction_sample_rate`. A span link will be made to the incoming `traceparent`. + +restart_external +: If an incoming request includes the `es` vendor flag in `tracestate`, then any `traceparent` will be considered internal and will be handled as described for **continue** above. Otherwise, any `traceparent` is considered external and will be handled as described for **restart** above. + +Starting with Elastic Observability 8.2, span links are visible in trace views. + diff --git a/docs/reference/contributing.md b/docs/reference/contributing.md new file mode 100644 index 000000000..bed37657a --- /dev/null +++ b/docs/reference/contributing.md @@ -0,0 +1,18 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/contributing.html +--- + +# Contributing [contributing] + +The Go APM Agent is open source and we love to receive contributions from our community — you! + +There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code. + +You can get in touch with us through [Discuss](https://discuss.elastic.co/c/apm). Feedback and ideas are always welcome. + + +## Reporting bugs and contributing code [_reporting_bugs_and_contributing_code] + +To report bugs, please create an Issue on the [apm-agent-go](https://github.com/elastic/apm-agent-go) GitHub repository. For tips on contributing code fixes or enhancements, please see the [contributing guide](https://github.com/elastic/apm-agent-go/blob/main/CONTRIBUTING.md) in the code repository. + diff --git a/docs/reference/custom-instrumentation-propagation.md b/docs/reference/custom-instrumentation-propagation.md new file mode 100644 index 000000000..73fe03a28 --- /dev/null +++ b/docs/reference/custom-instrumentation-propagation.md @@ -0,0 +1,89 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/custom-instrumentation-propagation.html +--- + +# Context propagation [custom-instrumentation-propagation] + +In Go, [context](https://golang.org/pkg/context/) is used to propagate request-scoped values along a call chain, potentially crossing between goroutines and between processes. For servers based on `net/http`, each request contains an independent context object, which allows adding values specific to that particular request. + +When you start a transaction, you can add it to a context object using [apm.ContextWithTransaction](/reference/api-documentation.md#apm-context-with-transaction). This context object can be later passed to [apm.TransactionFromContext](/reference/api-documentation.md#apm-transaction-from-context) to obtain the transaction, or into [apm.StartSpan](/reference/api-documentation.md#apm-start-span) to start a span. + +The simplest way to create and propagate a span is by using [apm.StartSpan](/reference/api-documentation.md#apm-start-span), which takes a context and returns a span. The span will be created as a child of the span most recently added to this context, or a transaction added to the context as described above. If the context contains neither a transaction nor a span, then the span will be dropped (i.e. will not be reported to the APM Server.) + +For example, take a simple CRUD-type web service, which accepts requests over HTTP and then makes corresponding database queries. For each incoming request, a transaction will be started and added to the request context automatically. This context needs to be passed into method calls within the handler manually in order to create spans within that transaction, e.g. to measure the duration of SQL queries. + +```go +import ( + "net/http" + + "go.elastic.co/apm/v2" + "go.elastic.co/apm/module/apmhttp/v2" + "go.elastic.co/apm/module/apmsql/v2" + _ "go.elastic.co/apm/module/apmsql/v2/pq" +) + +var db *sql.DB + +func init() { + // apmsql.Open wraps sql.Open, in order + // to add tracing to database operations. + db, _ = apmsql.Open("postgres", "") +} + +func main() { + mux := http.NewServeMux() + mux.HandleFunc("/", handleList) + + // apmhttp.Wrap instruments an http.Handler, in order + // to report any request to this handler as a transaction, + // and to store the transaction in the request's context. + handler := apmhttp.Wrap(mux) + http.ListenAndServe(":8080", handler) +} + +func handleList(w http.ResponseWriter, req *http.Request) { + // By passing the request context down to getList, getList can add spans to it. + ctx := req.Context() + getList(ctx) + ... +} + +func getList(ctx context.Context) ( + // When getList is called with a context containing a transaction or span, + // StartSpan creates a child span. In this example, getList is always called + // with a context containing a transaction for the handler, so we should + // expect to see something like: + // + // Transaction: handleList + // Span: getList + // Span: SELECT FROM items + // + span, ctx := apm.StartSpan(ctx, "getList", "custom") + defer span.End() + + // NOTE: The context object ctx returned by StartSpan above contains + // the current span now, so subsequent calls to StartSpan create new + // child spans. + + // db was opened with apmsql, so queries will be reported as + // spans when using the context methods. + rows, err := db.QueryContext(ctx, "SELECT * FROM items") + ... + rows.Close() +} +``` + +Contexts can have deadlines associated and can be explicitly canceled. In some cases you may wish to propagate the trace context (parent transaction/span) to some code without propagating the cancellation. For example, an HTTP request’s context will be canceled when the client’s connection closes. You may want to perform some operation in the request handler without it being canceled due to the client connection closing, such as in a fire-and-forget operation. To handle scenarios like this, we provide the function [apm.DetachedContext](/reference/api-documentation.md#apm-detached-context). + +```go +func handleRequest(w http.ResponseWriter, req *http.Request) { + go fireAndForget(apm.DetachedContext(req.Context())) + + // After handleRequest returns, req.Context() will be canceled, + // but the "detached context" passed into fireAndForget will not. + // Any spans created by fireAndForget will still be joined to + // the handleRequest transaction. +} +``` + diff --git a/docs/reference/custom-instrumentation.md b/docs/reference/custom-instrumentation.md new file mode 100644 index 000000000..ee912ce16 --- /dev/null +++ b/docs/reference/custom-instrumentation.md @@ -0,0 +1,65 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/custom-instrumentation.html +--- + +# Custom instrumentation [custom-instrumentation] + +To report on the performance of transactions served by your application, use the Go agent’s [API](/reference/api-documentation.md). Instrumentation refers to modifying your application code to report a: + +* [Transaction](#custom-instrumentation-transactions) - A top-level operation in your application, such as an HTTP or RPC request. +* [Span within a transaction](#custom-instrumentation-spans) - An operation within a transaction, such as a database query, or a request to another service. +* [Error](#custom-instrumentation-errors) - May refer to Go errors or panics. + +To report these, use a [apm.Tracer](/reference/api-documentation.md#tracer-api) — typically `apm.DefaultTracer()`, which is configured via environment variables. In the code examples below, we will refer to `apm.DefaultTracer()`. Please refer to the [API documentation](/reference/api-documentation.md) for a more thorough description of the types and methods. + +## Transactions [custom-instrumentation-transactions] + +To report a transaction, call [apm.DefaultTracer().StartTransaction](/reference/api-documentation.md#tracer-api-start-transaction) with the transaction name and type. This returns a `Transaction` object; the transaction can be customized with additional context before you call its `End` method to indicate that the transaction has completed. Once the transaction’s `End` method is called, it will be enqueued for sending to the Elastic APM server, and made available to the APM app. + +```go +tx := apm.DefaultTracer().StartTransaction("GET /api/v1", "request") +defer tx.End() +... +tx.Result = "HTTP 2xx" +tx.Context.SetLabel("region", "us-east-1") +``` + +The agent supports sampling transactions: non-sampled transactions will be still be reported, but with limited context and without any spans. To determine whether a transaction is sampled, use the `Transaction.Sampled` method; if it returns false, you should avoid unnecessary storage or processing required for setting transaction context. + +Once you have started a transaction, you can include it in a `context` object for propagating throughout the application. See [context propagation](/reference/custom-instrumentation-propagation.md) for more details. + +```go +ctx = apm.ContextWithTransaction(ctx, tx) +``` + + +## Spans [custom-instrumentation-spans] + +To report an operation within a transaction, use [Transaction.StartSpan](/reference/api-documentation.md#transaction-start-span) or [apm.StartSpan](/reference/api-documentation.md#apm-start-span) to start a span given a transaction or a `context` containing a transaction, respectively. Like a transaction, a span has a name and a type. A span can have a parent span within the same transaction. If the context provided to `apm.StartSpan` contains a span, then that will be considered the parent. See [context propagation](/reference/custom-instrumentation-propagation.md) for more details. + +```go +span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query") +defer span.End() +``` + +`Transaction.StartSpan` and `apm.StartSpan` will always return a non-nil `Span`, even if the transaction is nil. It is always safe to defer a call to the span’s End method. If setting the span’s context would incur significant overhead, you may want to check if the span is dropped first, by calling the `Span.Dropped` method. + + +## Panic recovery and errors [custom-instrumentation-errors] + +To recover panics and report them along with your transaction, use the [Tracer.Recovered](/reference/api-documentation.md#tracer-recovered) method in a recovery function. There are also methods for reporting non-panic errors: [Tracer.NewError](/reference/api-documentation.md#tracer-new-error), [Tracer.NewErrorLog](/reference/api-documentation.md#tracer-new-error-log), and [apm.CaptureError](/reference/api-documentation.md#apm-captureerror). + +```go +defer func() { + if v := recover(); v != nil { + e := apm.DefaultTracer().Recovered() + e.SetTransaction(tx) // or e.SetSpan(span) + e.Send() + } +}() +``` + +See the [Error API](/reference/api-documentation.md#error-api) for details and examples of the other methods. + + diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 000000000..1ea79bf18 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,28 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/introduction.html + - https://www.elastic.co/guide/en/apm/agent/go/current/index.html +--- + +# APM Go agent [introduction] + +The Elastic APM Go Agent enables you to trace the execution of operations in your [Go](https://golang.org/) applications, sending performance metrics and errors to the Elastic APM server. It has built-in support for popular frameworks and toolkits, like [Gorilla](http://www.gorillatoolkit.org/) and [Gin](https://gin-gonic.com/), as well as support for instrumenting Go’s built-in [net/http](https://golang.org/pkg/net/http/), [database/sql](https://golang.org/pkg/database/sql/) drivers. The Agent also offers an [*API Documentation*](/reference/api-documentation.md) for custom instrumentation. + + +## How does the Agent work? [how-it-works] + +The Agent includes instrumentation modules for [*Supported Technologies*](/reference/supported-technologies.md), each providing middleware or wrappers for recording interesting events, such as incoming HTTP requests, outgoing HTTP requests, and database queries. + +To collect data about incoming HTTP requests, install router middleware for one of the supported [Web Frameworks](/reference/supported-technologies.md#supported-tech-web-frameworks). Incoming requests will be recorded as transactions, along with any related panics or errors. + +To collect data for outgoing HTTP requests, instrument an `http.Client` or `http.Transport` using [module/apmhttp](/reference/builtin-modules.md#builtin-modules-apmhttp). To collect data about database queries, use [module/apmsql](/reference/builtin-modules.md#builtin-modules-apmsql), which provides instrumentation for well known database drivers. + +In order to connect transactions with related spans and errors, and propagate traces between services (distributed tracing), the agent relies on Go’s built-in [context](https://golang.org/pkg/context/) package: transactions and spans are stored in context objects. For example, for incoming HTTP requests, in-flight trace data will be recorded in the `context` object accessible through [net/http.Context](https://golang.org/pkg/net/http/#Request.Context). Read more about this in [Context propagation](/reference/custom-instrumentation-propagation.md). + +In addition to capturing events like those mentioned above, the agent also collects system and application metrics at regular intervals. This collection happens in a background goroutine that is automatically started when the agent is initialized. + + +## Additional Components [additional-components] + +APM Agents work in conjunction with the [APM Server](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apps/apm-agent-compatibility.md). + diff --git a/docs/reference/log-correlation.md b/docs/reference/log-correlation.md new file mode 100644 index 000000000..0cca6e380 --- /dev/null +++ b/docs/reference/log-correlation.md @@ -0,0 +1,94 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/log-correlation-ids.html +--- + +# Log correlation [log-correlation-ids] + +[Log correlation](docs-content://solutions/observability/apps/logs.md) allows you to navigate to all logs belonging to a particular trace and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided. + +In order to correlate logs from your app with transactions captured by the Elastic APM Go Agent, your logs must contain one or more of the following identifiers: + +* [`transaction.id`](ecs://reference/ecs-tracing.md) +* [`trace.id`](ecs://reference/ecs-tracing.md) +* [`span.id`](ecs://reference/ecs-error.md) + +In order to correlate the logs to the service and environment, the logs should also contain the following fields: + +* [`service.name`](ecs://reference/ecs-service.md) +* [`service.version`](ecs://reference/ecs-service.md) +* [`service.environment`](ecs://reference/ecs-service.md) + + +## Manual log correlation [log-correlation-manual] + +If the agent-provided logging integrations are not suitable or not available for your application, then you can use the agent’s [API](/reference/api-documentation.md) to inject trace IDs manually. There are two main approaches you can take, depending on whether you are using structured or unstructured logging. + + +### Manual log correlation (structured) [log-correlation-manual-structured] + +For correlating structured logs with traces and services, the fields defined above should be added to logs. + +Given a transaction object, you can obtain its trace ID and transaction ID using the [apm.Transaction.TraceContext](/reference/api-documentation.md#transaction-tracecontext) method. Similarly, given a span object, you can obtain its span ID using [apm.Span.TraceContext](/reference/api-documentation.md#span-tracecontext). + +If you use the context APIs to start transactions and spans, then you can obtain the context’s current transaction using [apm.TransactionFromContext](/reference/api-documentation.md#apm-transaction-from-context), and current span using [apm.SpanFromContext](/reference/api-documentation.md#apm-span-from-context). Note that if a transaction is not sampled, `apm.TransactionFromContext` will return `nil`. Similarly, spans may be dropped by the agent, so `apm.SpanFromContext` may also return `nil`. + +```go +labels := make(map[string]string) +tx := apm.TransactionFromContext(ctx) +if tx != nil { + traceContext := tx.TraceContext() + labels["trace.id"] = traceContext.Trace.String() + labels["transaction.id"] = traceContext.Span.String() + if span := apm.SpanFromContext(ctx); span != nil { + labels["span.id"] = span.TraceContext().Span + } +} +``` + +Follow this article to ingest JSON-encoded logs with Filebeat: [How to instrument your Go app with the Elastic APM Go agent](https://www.elastic.co/blog/how-to-instrument-your-go-app-with-the-elastic-apm-go-agent#logs). + + +### Manual log correlation (unstructured) [log-correlation-manual-unstructured] + +For correlating unstructured logs (e.g. basic printf-style logging, like the standard library’s `log` package), then you will need to need to include the trace IDs in your log message. Then, extract them using Filebeat. + +If you already have a transaction or span object, use the [Transaction.TraceContext](/reference/api-documentation.md#transaction-tracecontext) or [Span.TraceContext](/reference/api-documentation.md#span-tracecontext) methods. The trace, transaction, and span ID types all provide `String` methods that yield their canonical hex-encoded string representation. + +```go +traceContext := tx.TraceContext() +spanID := span.TraceContext().Span +log.Printf("ERROR [trace.id=%s transaction.id=%s span.id=%s] an error occurred", traceContext.Trace, traceContext.Span, spanID) +``` + +If instead you are dealing with context objects, you may prefer to use the [TraceFormatter](/reference/api-documentation.md#apm-traceformatter) function. For example, you could supply it as an argument to `log.Printf` as follows: + +```go +log.Printf("ERROR [%+v] an error occurred", apm.TraceFormatter(ctx)) +``` + +This would print a log message along the lines of: + +``` +2019/09/17 14:48:02 ERROR [trace.id=cd04f33b9c0c35ae8abe77e799f126b7 transaction.id=cd04f33b9c0c35ae span.id=960834f4538880a4] an error occurred +``` +For log correlation to work, the trace IDs must be extracted from the log message and stored in separate fields in the Elasticsearch document. This can be achieved by [using an ingest pipeline to parse the data](beats://reference/filebeat/configuring-ingest-node.md), in particular by using [the grok processor](elasticsearch://reference/ingestion-tools/enrich-processor/grok-processor.md). + +```json +{ + "description": "...", + "processors": [ + { + "grok": { + "field": "message", + "patterns": ["%{YEAR}/%{MONTHNUM}/%{MONTHDAY} %{TIME} %{LOGLEVEL:log.level} \\[trace.id=%{TRACE_ID:trace.id}(?: transaction.id=%{SPAN_ID:transaction.id})?(?: span.id=%{SPAN_ID:span.id})?\\] %{GREEDYDATA:message}"], + "pattern_definitions": { + "TRACE_ID": "[0-9A-Fa-f]{32}", + "SPAN_ID": "[0-9A-Fa-f]{16}" + } + } + } + ] +} +``` + diff --git a/docs/reference/logs.md b/docs/reference/logs.md new file mode 100644 index 000000000..8192f4010 --- /dev/null +++ b/docs/reference/logs.md @@ -0,0 +1,20 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/logs.html +--- + +# Logs [logs] + +Elastic APM Go Agent provides [*Log Correlation*](/reference/log-correlation.md). The agent will automaticaly inject correlation IDs that allow navigation between logs, traces and services. + +This features is part of [Application log ingestion strategies](docs-content://solutions/observability/logs/stream-application-logs.md). + +The [`ecslogrus`](ecs-logging-go-logrus://reference/index.md) and [`ecszap`](ecs-logging-go-zap://reference/index.md) libraries can also be used to use the [ECS logging](ecs-logging://reference/intro.md) format without an APM agent. When deployed with the Go APM agent, the agent will provide [log correlation](/reference/log-correlation.md) IDs. + +The Go agent provides integrations for popular logging frameworks that inject trace ID fields into the application’s log records. You can find a list of the supported logging frameworks under [supported technologies](/reference/supported-technologies.md#supported-tech-logging). + +If your favorite logging framework is not already supported, there are two other options: + +* Open a feature request, or contribute code, for additional support as described in [*Contributing*](/reference/contributing.md). +* Manually inject trace IDs into log records, as described below in [Manual log correlation](/reference/log-correlation.md#log-correlation-manual). + diff --git a/docs/reference/metrics.md b/docs/reference/metrics.md new file mode 100644 index 000000000..465d2d389 --- /dev/null +++ b/docs/reference/metrics.md @@ -0,0 +1,232 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/metrics.html +--- + +# Metrics [metrics] + +The Go agent periodically gathers and reports metrics. Control how often metrics are reported with the [`ELASTIC_APM_METRICS_INTERVAL`](/reference/configuration.md#config-metrics-interval) configuration, and disable metrics with [`ELASTIC_APM_DISABLE_METRICS`](/reference/configuration.md#config-disable-metrics). + + +## System metrics [metrics-system] + +The Go agent reports basic system-level and process-level CPU and memory metrics. For more system metrics, consider installing [Metricbeat](beats://reference/metricbeat/metricbeat.md) on your hosts. + +As of Elastic Stack version 6.6, these metrics will be visualized in the APM app. + +In some cases data from multiple nodes will be combined. As of Elastic Stack version 7.5, you will be able to set a unique name for each node to avoid this problem. Otherwise, data will be aggregated separately based on container ID or host name. + +**`system.cpu.total.norm.pct`** +: type: scaled_float + +format: percent + +The percentage of CPU time in states other than Idle and IOWait, normalised by the number of cores. + + +**`system.process.cpu.total.norm.pct`** +: type: scaled_float + +format: percent + +The percentage of CPU time spent by the process since the last event. This value is normalized by the number of CPU cores and it ranges from 0 to 100%. + + +**`system.memory.total`** +: type: long + +format: bytes + +Total memory. + + +**`system.memory.actual.free`** +: type: long + +format: bytes + +The actual memory in bytes. It is calculated based on the OS. On Linux it consists of the free memory plus caches and buffers. On OSX it is a sum of free memory and the inactive memory. On Windows, this value does not include memory consumed by system caches and buffers. + + +**`system.process.memory.size`** +: type: long + +format: bytes + +The total virtual memory the process has. + + + +## Go runtime metrics [metrics-golang] + +The Go agent reports various Go runtime metrics. + +::::{note} +As of now, there are no built-in visualizations for these metrics, so you will need to create custom Kibana dashboards for them. +:::: + + +**`golang.goroutines`** +: type: long + +The number of goroutines that currently exist. + + +**`golang.heap.allocations.mallocs`** +: type: long + +The number of mallocs. + + +**`golang.heap.allocations.frees`** +: type: long + +The number of frees. + + +**`golang.heap.allocations.objects`** +: type: long + +The total number of allocated objects. + + +**`golang.heap.allocations.total`** +: type: long + +format: bytes + +Bytes allocated (even if freed) throughout the lifetime. + + +**`golang.heap.allocations.allocated`** +: type: long + +format: bytes + +Bytes allocated and not yet freed (same as Alloc from [runtime.MemStats](https://golang.org/pkg/runtime/#MemStats)). + + +**`golang.heap.allocations.idle`** +: type: long + +format: bytes + +Bytes in idle spans. + + +**`golang.heap.allocations.active`** +: type: long + +format: bytes + +Bytes in non-idle spans. + + +**`golang.heap.system.total`** +: type: long + +format: bytes + +Total bytes obtained from system (sum of XxxSys from [runtime.MemStats](https://golang.org/pkg/runtime/#MemStats)). + + +**`golang.heap.system.obtained`** +: type: long + +format: bytes + +Via HeapSys from [runtime.MemStats](https://golang.org/pkg/runtime/#MemStats), bytes obtained from system. heap_sys = heap_idle + heap_inuse. + + +**`golang.heap.system.stack`** +: type: long + +format: bytes + +Bytes of stack memory obtained from the OS. + + +**`golang.heap.system.released`** +: type: long + +format: bytes + +Bytes released to the OS. + + +**`golang.heap.gc.total_pause.ns`** +: type: long + +The total garbage collection duration in nanoseconds. + + +**`golang.heap.gc.total_count`** +: type: long + +The total number of garbage collections. + + +**`golang.heap.gc.next_gc_limit`** +: type: long + +format: bytes + +Target heap size of the next garbage collection cycle. + + +**`golang.heap.gc.cpu_fraction`** +: type: float + +Fraction of CPU time used by garbage collection. + + + +## Application Metrics [metrics-application] + +**`transaction.duration`** +: type: simple timer + +This timer tracks the duration of transactions and allows for the creation of graphs displaying a weighted average. + +Fields: + +* `sum.us`: The sum of all transaction durations in microseconds since the last report (the delta) +* `count`: The count of all transactions since the last report (the delta) + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` + + +**`transaction.breakdown.count`** +: type: long + +format: count (delta) + +The number of transactions for which breakdown metrics (`span.self_time`) have been created. As the Go agent tracks the breakdown for both sampled and non-sampled transactions, this metric is equivalent to `transaction.duration.count` + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` + + +**`span.self_time`** +: type: simple timer + +This timer tracks the span self-times and is the basis of the transaction breakdown visualization. + +Fields: + +* `sum.us`: The sum of all span self-times in microseconds since the last report (the delta) +* `count`: The count of all span self-times since the last report (the delta) + +You can filter and group by these dimensions: + +* `transaction.name`: The name of the transaction +* `transaction.type`: The type of the transaction, for example `request` +* `span.type`: The type of the span, for example `app`, `template` or `db` +* `span.subtype`: The sub-type of the span, for example `mysql` (optional) + + diff --git a/docs/opentelemetry.asciidoc b/docs/reference/opentelemetry-api.md similarity index 58% rename from docs/opentelemetry.asciidoc rename to docs/reference/opentelemetry-api.md index 6e1b5de4c..a33d804f7 100644 --- a/docs/opentelemetry.asciidoc +++ b/docs/reference/opentelemetry-api.md @@ -1,48 +1,40 @@ -[[opentelemetry]] -== OpenTelemetry API +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/opentelemetry.html +--- -The Elastic APM Go Agent provides wrappers to interact with the https://opentelemetry.io/[OpenTelemetry API]. +# OpenTelemetry API [opentelemetry] + +The Elastic APM Go Agent provides wrappers to interact with the [OpenTelemetry API](https://opentelemetry.io/). Traces and metrics created through the OpenTelemetry API will be translated to their Elastic APM equivalent. -[float] -=== Initializing the tracing bridge -The OpenTelemetry Tracing bridge is implemented as a Tracer Provider. Once -setup, any span created through that provider will be set on the Elastic -agent. -And the provider will try to find any existing transaction within the context. +## Initializing the tracing bridge [_initializing_the_tracing_bridge] + +The OpenTelemetry Tracing bridge is implemented as a Tracer Provider. Once setup, any span created through that provider will be set on the Elastic agent. And the provider will try to find any existing transaction within the context. -Note: our tracer provider bridge is an incomplete implementation of an -OpenTelemetry SDK. It is a good solution meant to help migrate from our agent -to OpenTelemetry, but shouldn't be considered as a long-term solution. +Note: our tracer provider bridge is an incomplete implementation of an OpenTelemetry SDK. It is a good solution meant to help migrate from our agent to OpenTelemetry, but shouldn’t be considered as a long-term solution. To setup this tracer provider, you first need to import the `apmotel` package. -[source,go] ----- +```go import ( "go.elastic.co/apm/module/apmotel/v2" ) ----- - -The apmotel package exposes a `NewTracerProvider` method, which returns an -implementation of an OpenTelemetry Tracer Provider. +``` +The apmotel package exposes a `NewTracerProvider` method, which returns an implementation of an OpenTelemetry Tracer Provider. -[source,go] ----- +```go provider, err := apmotel.NewTracerProvider() ----- +``` -By default, the tracer provider will find the default apm tracer. But you can -specify a custom one with the `apmotel.WithAPMTracer` argument option. +By default, the tracer provider will find the default apm tracer. But you can specify a custom one with the `apmotel.WithAPMTracer` argument option. -Once you have obtained this provider, you can configure it as your -OpenTelemetry SDK implementation, and use the APIs normally. +Once you have obtained this provider, you can configure it as your OpenTelemetry SDK implementation, and use the APIs normally. -[source,go] ----- +```go import ( "go.elastic.co/apm/v2" "go.elastic.co/apm/module/apmotel/v2" @@ -50,7 +42,7 @@ import ( "go.opentelemetry.io/otel" ) -func main() { +func main() { provider, err := apmotel.NewTracerProvider() if err != nil { log.Fatal(err) @@ -63,45 +55,37 @@ func main() { // Do something span.End() } ----- +``` -[float] -[[opentelemetry-metrics-init]] -=== Initializing the metrics exporter -preview::["The Metrics Exporter is in technical preview until OpenTelemetry marks them as GA."] +## Initializing the metrics exporter [opentelemetry-metrics-init] -The OpenTelemetry Metrics bridge is implemented as a manual reader exporter. -The Elastic APM Agent will regularly ask OpenTelemetry for its latest metrics, -and emit them as its own. +::::{warning} +The Metrics Exporter is in technical preview until OpenTelemetry marks them as GA. +:::: -To initialize this exporter, you first need to import the `apmotel` package. +The OpenTelemetry Metrics bridge is implemented as a manual reader exporter. The Elastic APM Agent will regularly ask OpenTelemetry for its latest metrics, and emit them as its own. -[source,go] ----- +To initialize this exporter, you first need to import the `apmotel` package. + +```go import ( "go.elastic.co/apm/module/apmotel" ) ----- +``` -The apmotel package exposes a `NewGatherer` method, which returns an implementation of both an https://pkg.go.dev/github.com/elastic/apm-agent-go#MetricsGatherer[Elastic MetricsGatherer], and an https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#Reader[OpenTelemetry metric.Reader]. +The apmotel package exposes a `NewGatherer` method, which returns an implementation of both an [Elastic MetricsGatherer](https://pkg.go.dev/github.com/elastic/apm-agent-go#MetricsGatherer), and an [OpenTelemetry metric.Reader](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#Reader). -[source,go] ----- +```go exporter := apmotel.NewGatherer() ----- +``` -The method allows passing some options, such as `WithAggregationSelector`, to -specify a custom OpenTelemetry aggregation selector. +The method allows passing some options, such as `WithAggregationSelector`, to specify a custom OpenTelemetry aggregation selector. -Once you have obtained this exporter, you can configure the OpenTelemetry SDK -so it reports emitted metrics, as well as the Elastic Agent to read those -metrics. +Once you have obtained this exporter, you can configure the OpenTelemetry SDK so it reports emitted metrics, as well as the Elastic Agent to read those metrics. - -[source,go] ----- +```go import ( "go.elastic.co/apm" "go.elastic.co/apm/module/apmotel" @@ -125,4 +109,5 @@ func main() { counter, _ := meter.Float64Counter("metric_called") counter.Add(context.TODO(), 1) } ----- +``` + diff --git a/docs/reference/opentracing-api.md b/docs/reference/opentracing-api.md new file mode 100644 index 000000000..9ae848a31 --- /dev/null +++ b/docs/reference/opentracing-api.md @@ -0,0 +1,108 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/opentracing.html +--- + +# OpenTracing API [opentracing] + +The Elastic APM Go agent provides an implementation of the [OpenTracing API](https://opentracing.io), building on top of the core Elastic APM API. + +Spans created through the OpenTracing API will be translated to Elastic APM transactions or spans. Root spans, and spans created with a remote span context, will be translated to Elastic APM transactions. All others will be created as Elastic APM spans. + + +## Initializing the tracer [opentracing-init] + +The OpenTracing API implementation is implemented as a bridge on top of the core Elastic APM API. To initialize the OpenTracing tracer implementation, you must first import the `apmot` package: + +```go +import ( + "go.elastic.co/apm/module/apmot/v2" +) +``` + +The apmot package exports a function, "New", which returns an implementation of the `opentracing.Tracer` interface. If you call `apmot.New()` without any arguments, the returned tracer will wrap `apm.DefaultTracer()`. If you wish to use a different `apm.Tracer`, then you can pass it with `apmot.New(apmot.WithTracer(t))`. + +```go +otTracer := apmot.New() +``` + +Once you have obtained an `opentracing.Tracer`, use the standard OpenTracing API to report spans to Elastic APM. Please refer to [opentracing-go](https://github.com/opentracing/opentracing-go) for documentation on the OpenTracing Go API. + +```go +import ( + "context" + + "go.elastic.co/apm/module/apmot/v2" + + "github.com/opentracing/opentracing-go" +) + +func main() { + opentracing.SetGlobalTracer(apmot.New()) + + parent, ctx := opentracing.StartSpanFromContext(context.Background(), "parent") + child, _ := opentracing.StartSpanFromContext(ctx, "child") + child.Finish() + parent.Finish() +} +``` + + +## Mixing Native and OpenTracing APIs [opentracing-mixed] + +When you import `apmot`, transactions and spans created with the [native API](/reference/api-documentation.md) will be made available as OpenTracing spans, enabling you to mix the use of the native and OpenTracing APIs. e.g.: + +```go +// Transaction created through native API. +transaction := apm.DefaultTracer().StartTransaction("GET /", "request") +ctx := apm.ContextWithTransaction(context.Background(), transaction) + +// Span created through OpenTracing API will be a child of the transaction. +otSpan, ctx := opentracing.StartSpanFromContext(ctx, "ot-span") + +// Span created through the native API will be a child of the span created +// above via the OpenTracing API. +apmSpan, ctx := apm.StartSpan(ctx, "apm-span", "apm-span") +``` + +The `opentracing.SpanFromContext` function will return an `opentracing.Span` that wraps either an `apm.Span` or `apm.Transaction`. These span objects are intended only for passing in context when creating a new span through the OpenTracing API, and are not fully functional spans. In particular, the `Finish` and `Log*` methods are no-ops, and the `Tracer` method returns a no-op tracer. + + +## Elastic APM specific tags [opentracing-apm-tags] + +Elastic APM defines some tags which are not included in the OpenTracing API, but are relevant in the context of Elastic APM. Some tags are relevant only to Elastic APM transactions. + +* `type` - sets the type of the transaction or span, e.g. "request", or "ext.http". If `type` is not specified, then the type may be inferred from other tags. e.g. if "http.url" is specified, then the type will be "request" for transactions, and "ext.http" for spans. If no type can be inferred, it is set to "unknown". + +The following tags are relevant only to root or service-entry spans, which are translated to Elastic APM transactions: + +* `user.id` - sets the user ID, which appears in the "User" tab in the transaction details in the Elastic APM app +* `user.email` - sets the user email, which appears in the "User" tab in the transaction details in the Elastic APM app +* `user.username` - sets the user name, which appears in the "User" tab in the transaction details in the Elastic APM app +* `result` - sets the result of the transaction. If `result` is *not* specified, but `error` tag is set to `true`, then the transaction result will be set to "error" + + +## Span Logs [opentracing-logs] + +The `Span.LogKV` and `Span.LogFields` methods will send error events to Elastic APM for logs with the "event" field set to "error". + +The deprecated log methods `Span.Log`, `Span.LogEvent`, and `Span.LogEventWithPayload` are no-ops. + + +## Caveats [opentracing-caveats] + + +### Context Propagation [opentracing-caveats-propagation] + +We support the `TextMap` and `HTTPHeaders` propagation formats; `Binary` is not currently supported. + + +### Span References [opentracing-caveats-spanrefs] + +We support only `ChildOf` references. Other references, e.g. `FollowsFrom`, are not currently supported. + + +### Baggage [opentracing-caveats-baggage] + +`Span.SetBaggageItem` is a no-op; baggage items are silently dropped. + diff --git a/docs/reference/set-up-apm-go-agent.md b/docs/reference/set-up-apm-go-agent.md new file mode 100644 index 000000000..27b768272 --- /dev/null +++ b/docs/reference/set-up-apm-go-agent.md @@ -0,0 +1,47 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/getting-started.html +--- + +# Set up the APM Go Agent [getting-started] + +To start reporting your Go application’s performance to Elastic APM, you need to do a few things: + +1. [Install the Agent](#installation). +2. [Instrument Go Source Code](#instrumenting-source). +3. [Configure the Agent](#configure-setup). + + +## Install the Agent [installation] + +Within a Go module, install the Elastic APM Go agent package using `go get`: + +```bash +go get -u go.elastic.co/apm/v2 +``` + + +### Requirements [_requirements] + +You can find a list of the supported frameworks and other technologies in the [*Supported Technologies*](/reference/supported-technologies.md) section. + + +## Instrument Go Source Code [instrumenting-source] + +Instrumentation is the process of extending your application’s code to report trace data to Elastic APM. Go applications must be instrumented manually at the source code level. There are two ways to instrument your applications: + +* Using [Built-in instrumentation modules](/reference/builtin-modules.md). +* [Custom instrumentation](/reference/custom-instrumentation.md) and [Context propagation](/reference/custom-instrumentation-propagation.md) with the Go Agent API. + +Where possible, use the built-in modules to report transactions served by web and RPC frameworks in your application. + + +## Configure the Agent [configure-setup] + +To simplify development and testing, the agent defaults to sending data to the Elastic APM Server at `http://localhost:8200`. To send data to an alternative location, you must configure [ELASTIC_APM_SERVER_URL](/reference/configuration.md#config-server-url). Depending on the configuration of your server, you may also need to set [ELASTIC_APM_API_KEY](/reference/configuration.md#config-api-key), [ELASTIC_APM_SECRET_TOKEN](/reference/configuration.md#config-secret-token), and [ELASTIC_APM_VERIFY_SERVER_CERT](/reference/configuration.md#config-verify-server-cert). All other variables have usable defaults. + +See [*Configuration*](/reference/configuration.md) to learn about all available options. + + + + diff --git a/docs/reference/supported-technologies.md b/docs/reference/supported-technologies.md new file mode 100644 index 000000000..c013560bb --- /dev/null +++ b/docs/reference/supported-technologies.md @@ -0,0 +1,262 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/supported-tech.html +--- + +# Supported technologies [supported-tech] + +This page describes the technologies supported by the Elastic APM Go agent. + +If your favorite technology is not supported yet, you start a conversation in the [Discuss forum](https://discuss.elastic.co/c/apm). + +If you would like to get more involved, take a look at the [contributing guide](/reference/contributing.md). + + +## Go [supported-tech-go] + +The Elastic APM Go agent naturally requires Go. We support the last two major Go releases as described by [Go’s Release Policy](https://golang.org/doc/devel/release.md#policy): + +[TBC: QUOTE] + +## Web Frameworks [supported-tech-web-frameworks] + +We support several third-party web frameworks, as well as Go’s standard `net/http` package. Regardless of the framework, we create a transaction for each incoming request, and name the transaction after the registered route. + + +### fasthttp [_fasthttp] + +We support [valyala/fasthttp](https://github.com/valyala/fasthttp), [v1.26.0](https://github.com/valyala/fasthttp/releases/tag/v1.26.0) and greater. + +See [module/apmfasthttp](/reference/builtin-modules.md#builtin-modules-apmfasthttp) for more information about fasthttp instrumentation. + + +### httprouter [_httprouter] + +[julienschmidt/httprouter](https://github.com/julienschmidt/httprouter) does not use semantic versioning, but its API is relatively stable. Any recent version should be compatible with the Elastic APM Go agent. + +See [module/apmhttprouter](/reference/builtin-modules.md#builtin-modules-apmhttprouter) for more information about httprouter instrumentation. + + +### Echo [_echo] + +We support the [Echo](https://echo.labstack.com/) web framework, [v3.3.5](https://github.com/labstack/echo/releases/tag/3.3.5) and greater. + +We provide different packages for the Echo v3 and v4 versions: `module/apmecho` for Echo v3.x, and `module/apmechov4` for Echo v4.x. + +See [module/apmecho](/reference/builtin-modules.md#builtin-modules-apmecho) for more information about Echo instrumentation. + + +### Gin [_gin] + +We support the [Gin](https://gin-gonic.com/) web framework, [v1.2](https://github.com/gin-gonic/gin/releases/tag/v1.2) and greater. + +See [module/apmgin](/reference/builtin-modules.md#builtin-modules-apmgin) for more information about Gin instrumentation. + + +### Fiber [_fiber] + +We support the [Fiber](https://gofiber.io/) web framework, [v2.18.0](https://github.com/gofiber/fiber/releases/tag/v2.18.0) and greater. + +We provide package only for the Fiber v2. See [module/apmfiber](/reference/builtin-modules.md#builtin-modules-apmfiber) for more information about Fiber instrumentation. + + +### Beego [_beego] + +We support the [Beego](https://beego.me/) web framework, [v1.10.0](https://github.com/astaxie/beego/releases/tag/v1.10.0) and greater. + +See [module/apmbeego](/reference/builtin-modules.md#builtin-modules-apmbeego) for more information about Beego instrumentation. + + +### gorilla/mux [_gorillamux] + +We support [gorilla/mux](http://www.gorillatoolkit.org/pkg/mux) [v1.6.1](https://github.com/gorilla/mux/releases/tag/v1.6.1) and greater. Older versions are not supported due to the use of gorilla.Middleware. + +See [module/apmgorilla](/reference/builtin-modules.md#builtin-modules-apmgorilla) for more information about gorilla/mux instrumentation. + + +### go-restful [_go_restful] + +We support [go-restful](https://github.com/emicklei/go-restful), [2.0.0](https://github.com/emicklei/go-restful/releases/tag/2.0.0) and greater. + +See [module/apmrestful](/reference/builtin-modules.md#builtin-modules-apmrestful) for more information about go-restful instrumentation. + + +### chi [_chi] + +We support [chi](https://github.com/go-chi/chi), [v4.0.0](https://github.com/go-chi/chi/releases/tag/v4.0.0) and greater. + +See [module/apmchi](/reference/builtin-modules.md#builtin-modules-apmchi) for more information about chi instrumentation. + + +### negroni [_negroni] + +We support [negroni](https://github.com/urfave/negroni), [v1.0.0](https://github.com/urfave/negroni/releases/tag/v1.0.0) and greater. + +See [module/apmnegroni](/reference/builtin-modules.md#builtin-modules-apmnegroni) for more information about negroni instrumentation. + + +## Databases [supported-tech-databases] + + +### database/sql [_databasesql] + +We support tracing requests with any `database/sql` driver, provided the driver is registered with the Elastic APM Go agent. Spans will be created for each statemented executed. + +When using one of the following drivers, the Elastic APM Go agent will be able to parse the datasource name, and provide more context in the spans it emits: + +* [lib/pq](https://github.com/lib/pq) (PostgreSQL) +* [jackc/pgx](https://github.com/jackc/pgx) (PostgreSQL) +* [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) +* [mattn/go-sqlite3](https://github.com/go-sqlite3) + +See [module/apmsql](/reference/builtin-modules.md#builtin-modules-apmsql) for more information about database/sql instrumentation. + + +### GORM [_gorm] + +We support the [GORM](http://gorm.io/) object-relational mapping library, [v1.9](https://github.com/jinzhu/gorm/releases/tag/v1.9) and greater. Spans will be created for each create, query, update, and delete operation. + +As with `database/sql` support we provide additional support for the postgres, mysql, and sqlite dialects. + +We provide different packages for the Gorm v1 and v2 versions: `module/apmgorm` for Gorm v1.x, and `module/apmgormv2` for Gorm v2.x. + +See [module/apmgorm](/reference/builtin-modules.md#builtin-modules-apmgorm) or [module/apmgormv2](/reference/builtin-modules.md#builtin-modules-apmgorm) for more information about GORM instrumentation. + + +### go-pg/pg [_go_pgpg] + +We support the [go-pg/pg](https://github.com/go-pg/pg) PostgreSQL ORM, [v8.0.4](https://github.com/go-pg/pg/releases/tag/v8.0.4). Spans will be created for each database operation. + +See [module/apmgopg](/reference/builtin-modules.md#builtin-modules-apmgopg) for more information about go-pg instrumentation. + + +### Cassandra (gocql) [_cassandra_gocql] + +[GoCQL](https://gocql.github.io/) does not have a stable API, so we will provide support for the most recent API, and older versions of the API on a best-effort basis. Spans will be created for each query. When the batch API is used, a span will be created for the batch, and a sub-span is created for each query in the batch. + +See [module/apmgocql](/reference/builtin-modules.md#builtin-modules-apmgocql) for more information about GoCQL instrumentation. + + +### Redis (gomodule/redigo) [_redis_gomoduleredigo] + +We support [Redigo](https://github.com/gomodule/redigo), [v2.0.0](https://github.com/gomodule/redigo/tree/v2.0.0) and greater. We provide helper functions for reporting Redis commands as spans. + +See [module/apmredigo](/reference/builtin-modules.md#builtin-modules-apmredigo) for more information about Redigo instrumentation. + + +### Redis (go-redis/redis) [_redis_go_redisredis] + +We support [go-redis](https://github.com/go-redis/redis), [v6.15.3](https://github.com/go-redis/redis/tree/v6.15.3). We provide helper functions for reporting Redis commands as spans. + +See [module/apmgoredis](/reference/builtin-modules.md#builtin-modules-apmgoredis) for more information about go-redis instrumentation. + + +### Elasticsearch [_elasticsearch] + +We provide instrumentation for Elasticsearch clients. This is usable with the [go-elasticsearch](https://github.com/elastic/go-elasticsearch) and [olivere/elastic](https://github.com/olivere/elastic) clients, and should also be usable with any other clients that provide a means of configuring the underlying `net/http.RoundTripper`. + +See [module/apmelasticsearch](/reference/builtin-modules.md#builtin-modules-apmelasticsearch) for more information about Elasticsearch client instrumentation. + + +### MongoDB [_mongodb] + +We provide instrumentation for the official [MongoDB Go Driver](https://github.com/mongodb/mongo-go-driver), [v1.0.0](https://github.com/mongodb/mongo-go-driver/releases/tag/v1.0.0) and greater. Spans will be created for each MongoDB command executed within a context containing a transaction. + +See [module/apmmongo](/reference/builtin-modules.md#builtin-modules-apmmongo) for more information about the MongoDB Go Driver instrumentation. + + +### DynamoDB [_dynamodb] + +We provide instrumentation for AWS DynamoDB. This is usable with [AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See [module/apmawssdkgo](/reference/builtin-modules.md#builtin-modules-apmawssdkgo) for more information about AWS SDK Go instrumentation. + + +## RPC Frameworks [supported-tech-rpc] + + +### gRPC [_grpc] + +We support [gRPC](https://grpc.io/) [v1.3.0](https://github.com/grpc/grpc-go/releases/tag/v1.3.0) and greater. We provide unary and stream interceptors for both the client and server. The server interceptor will create a transaction for each incoming request, and the client interceptor will create a span for each outgoing request. + +See [module/apmgrpc](/reference/builtin-modules.md#builtin-modules-apmgrpc) for more information about gRPC instrumentation. + + +## Service Frameworks [supported-tech-services] + + +### Go kit [_go_kit] + +We support tracing [Go kit](https://gokit.io/) clients and servers when using the gRPC or HTTP transport, by way of [module/apmgrpc](/reference/builtin-modules.md#builtin-modules-apmgrpc) and [module/apmhttp](/reference/builtin-modules.md#builtin-modules-apmhttp) respectively. + +Code examples are available at [https://pkg.go.dev/go.elastic.co/apm/module/apmgokit/v2](https://pkg.go.dev/go.elastic.co/apm/module/apmgokit/v2) for getting started. + + +## Logging frameworks [supported-tech-logging] + + +### Logrus [_logrus] + +We support log correlation and exception tracking with [Logrus](https://github.com/sirupsen/logrus/), [v1.1.0](https://github.com/sirupsen/logrus/releases/tag/v1.1.0) and greater. + +See [module/apmlogrus](/reference/builtin-modules.md#builtin-modules-apmlogrus) for more information about Logrus integration. + + +### Zap [_zap] + +We support log correlation and exception tracking with [Zap](https://github.com/uber-go/zap/), [v1.0.0](https://github.com/uber-go/zap/releases/tag/v1.0.0) and greater. + +See [module/apmzap](/reference/builtin-modules.md#builtin-modules-apmzap) for more information about Zap integration. + + +### Zerolog [_zerolog] + +We support log correlation and exception tracking with [Zerolog](https://github.com/rs/zerolog/), [v1.12.0](https://github.com/rs/zerolog/releases/tag/v1.12.0) and greater. + +See [module/apmzerolog](/reference/builtin-modules.md#builtin-modules-apmzerolog) for more information about Zerolog integration. + + +### Slog [_slog] + +We support log correlation and error tracking with [Slog](https://pkg.go.dev/log/slog/), [v1.21.0](https://pkg.go.dev/log/slog@go1.21.0/) and greater. + +See [module/apmslog](/reference/builtin-modules.md#builtin-modules-apmslog) for more information about slog integration. + + +## Object Storage [supported-tech-object-storage] + + +### Amazon S3 [_amazon_s3] + +We provide instrumentation for AWS S3. This is usable with [AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See [module/apmawssdkgo](/reference/builtin-modules.md#builtin-modules-apmawssdkgo) for more information about AWS SDK Go instrumentation. + + +### Azure Storage [_azure_storage] + +We provide instrumentation for Azure Storage. This is usable with: + +* github.com/Azure/azure-storage-blob-go/azblob[Azure Blob Storage] +* github.com/Azure/azure-storage-queue-go/azqueue[Azure Queue Storage] +* github.com/Azure/azure-storage-file-go/azfile[Azure File Storage] + +See [module/apmazure](/reference/builtin-modules.md#builtin-modules-apmazure) for more information about Azure SDK Go instrumentation. + + +## Messaging Systems [supported-tech-messaging-systems] + + +### Amazon SQS [_amazon_sqs] + +We provide instrumentation for AWS SQS. This is usable with [AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See [module/apmawssdkgo](/reference/builtin-modules.md#builtin-modules-apmawssdkgo) for more information about AWS SDK Go instrumentation. + + +### Amazon SNS [_amazon_sns] + +We provide instrumentation for AWS SNS. This is usable with [AWS SDK Go](https://github.com/aws/aws-sdk-go). + +See [module/apmawssdkgo](/reference/builtin-modules.md#builtin-modules-apmawssdkgo) for more information about AWS SDK Go instrumentation. + diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml new file mode 100644 index 000000000..cca2e37c3 --- /dev/null +++ b/docs/reference/toc.yml @@ -0,0 +1,18 @@ +project: 'APM Go agent reference' +toc: + - file: index.md + - file: set-up-apm-go-agent.md + children: + - file: builtin-modules.md + - file: custom-instrumentation.md + - file: custom-instrumentation-propagation.md + - file: supported-technologies.md + - file: configuration.md + - file: api-documentation.md + - file: metrics.md + - file: logs.md + - file: log-correlation.md + - file: opentelemetry-api.md + - file: opentracing-api.md + - file: contributing.md + - file: upgrading.md \ No newline at end of file diff --git a/docs/reference/upgrading.md b/docs/reference/upgrading.md new file mode 100644 index 000000000..4d3721c23 --- /dev/null +++ b/docs/reference/upgrading.md @@ -0,0 +1,19 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/upgrading.html +--- + +# Upgrading [upgrading] + +Upgrades between minor versions of the agent, like from 1.1 to 1.2 are always backwards compatible. Upgrades that involve a major version bump often come with some backwards incompatible changes. + +Before upgrading the agent, be sure to review the: + +* [Agent release notes](/release-notes/index.md) +* [Agent and Server compatibility chart](docs-content://solutions/observability/apps/apm-agent-compatibility.md) + + +## End of life dates [end-of-life-dates] + +We love all our products, but sometimes we must say goodbye to a release so that we can continue moving forward on future development and innovation. Our [End of life policy](https://www.elastic.co/support/eol) defines how long a given release is considered supported, as well as how long a release is considered still in active development or maintenance. + diff --git a/docs/release-notes.asciidoc b/docs/release-notes.asciidoc deleted file mode 100644 index 6a04f9c1d..000000000 --- a/docs/release-notes.asciidoc +++ /dev/null @@ -1,17 +0,0 @@ -:pull: https://github.com/elastic/apm-agent-go/pull/ - -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/agent/go[elastic.co] -endif::[] - -[[release-notes]] -== Release notes - -All notable changes to this project will be documented here. - -* <> -* <> -* <> - -include::../CHANGELOG.asciidoc[] diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md new file mode 100644 index 000000000..8432ef3b4 --- /dev/null +++ b/docs/release-notes/index.md @@ -0,0 +1,198 @@ +--- +navigation_title: "Elastic APM Go Agent" +mapped_pages: + - https://www.elastic.co/guide/en/apm/agent/go/current/release-notes-2.x.html + - https://www.elastic.co/guide/en/apm/agent/go/current/release-notes.html +--- + +# Elastic APM Go Agent release notes [elastic-apm-go-agent-release-notes] + +Review the changes, fixes, and more in each version of Elastic APM Go Agent. + +To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31). + +% Release notes includes only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections. + +% version.next [elastic-apm-go-agent-versionext-release-notes] +% **Release date:** Month day, year + +% ### Features and enhancements [elastic-apm-go-agent-versionext-features-enhancements] + +% ### Fixes [elastic-apm-go-agent-versionext-fixes] + +## 2.6.3 [elastic-apm-go-agent-263-release-notes] +**Release date:** January 13, 2025 + +### Fixes [elastic-apm-go-agent-263-fixes] +* avoid panic when unwrapping errors + +## 2.6.2 [elastic-apm-go-agent-262-release-notes] +**Release date:** August 29, 2025 + +### Features and enhancements [elastic-apm-go-agent-262-features-enhancements] +* update version string + +## 2.6.1 [elastic-apm-go-agent-261-release-notes] +**Release date:** August 29, 2024 + +### Features and enhancements [elastic-apm-go-agent-261-features-enhancements] +* support all upstream GOOS [#1646](https://github.com/elastic/apm-agent-go/pull/1646) + +### Fixes [elastic-apm-go-agent-261-fixes] +* apm.DefaultTracer misbehaves when transport configuration is invalid by [#1618](https://github.com/elastic/apm-agent-go/pull/1618) +* gin web framework does not properly sanitize filename parameter of Context.FileAttachment function [#1620](https://github.com/elastic/apm-agent-go/pull/1620) + +## 2.6.0 [elastic-apm-go-agent-260-release-notes] +**Release date:** April 11, 2024 + +### Features and enhancements [elastic-apm-go-agent-260-features-enhancements] +* Bump minimum Go version to 1.21 [#1602](https://github.com/elastic/apm-agent-go/pull/1602) + +### Fixes [elastic-apm-go-agent-260-fixes] +* module/apmotel: fix compatibility issue with newer version of otel libs. [#1605](https://github.com/elastic/apm-agent-go/pull/1605) + +## 2.5.0 [elastic-apm-go-agent-250-release-notes] +**Release date:** March 12, 2024 + +### Features and enhancements [elastic-apm-go-agent-250-features-enhancements] +* module/apmgorm: Switch from `github.com/denisenkom/go-mssqldb` package to `github.com/microsoft/go-mssqldb`. [#1569](https://github.com/elastic/apm-agent-go/pull/1569) +* module/apmrestful: Upgrade `github.com/emicklei/go-restful` package to `gituhub.co/emicklei/go-restful/v3`. [#1580](https://github.com/elastic/apm-agent-go/pull/1580) + +## 2.4.8 [elastic-apm-go-agent-248-release-notes] +**Release date:** March 12, 2024 + +### Features and enhancements [elastic-apm-go-agent-248-features-enhancements] +* module/apmotel: Add nil and recording check to span.RecordError [#1566](https://github.com/elastic/apm-agent-go/pull/1566) + +## 2.4.7 [elastic-apm-go-agent-247-release-notes] +**Release date:** November 23, 2024 + +### Features and enhancements [elastic-apm-go-agent-247-features-enhancements] +* Bump submodule dependency version [#1546](https://github.com/elastic/apm-agent-go/pull/1546) + +## 2.4.6 [elastic-apm-go-agent-246-release-notes] +**Release date:** November 22, 2023 + +### Fixes [elastic-apm-go-agent-246-fixes] +* module/apmotel: Fix compatibility issue with newer version of otel [#1544](https://github.com/elastic/apm-agent-go/pull/1544) + +## 2.4.5 [elastic-apm-go-agent-245-release-notes] +**Release date:** October 11, 2023 + +### Fixes [elastic-apm-go-agent-245-fixes] +* module/apmotel: Fix panic on multiple span close calls [#1512](https://github.com/elastic/apm-agent-go/pull/1512) + +## 2.4.4 [elastic-apm-go-agent-244-release-notes] +**Release date:** August 29, 2023 + +### Features and enhancements [elastic-apm-go-agent-244-features-enhancements] +* module/apmotel: Bumped minimum OpenTelemetry version [#1501](https://github.com/elastic/apm-agent-go/pull/1501) +* module/apmotel: Return usable spans when retrieving them from otel.SpanFromContext [#1478](https://github.com/elastic/apm-agent-go/pull/1478) + +### Fixes [elastic-apm-go-agent-244-fixes] +* Fixed concurrent map write condition where some child spans couldn’t acquire the transaction lock [#1487](https://github.com/elastic/apm-agent-go/pull/1487) + +## 2.4.3 [elastic-apm-go-agent-243-release-notes] +**Release date:** June 22, 2023 + +### Features and enhancements [elastic-apm-go-agent-243-features-enhancements] +* Bumped minimum Go version to 1.19 [#1453](https://github.com/elastic/apm-agent-go/pull/1453) +* Updated to stable OTel metrics API [#1448](https://github.com/elastic/apm-agent-go/pull/1448) + +### Fixes [elastic-apm-go-agent-243-fixes] +* Fixed a data race in HTTP client instrumentation [#1472](https://github.com/elastic/apm-agent-go/pull/1472) +* Fixed mixing of OTel and Elastic APM instrumentation [#1450](https://github.com/elastic/apm-agent-go/pull/1450) + +## 2.4.2 [elastic-apm-go-agent-242-release-notes] +**Release date:** May 22, 2023 + +### Features and enhancements [elastic-apm-go-agent-242-features-enhancements] +* module/apmotel: handle resources [#1424](https://github.com/elastic/apm-agent-go/pull/1424) +* Drop x/net dependency [#1434](https://github.com/elastic/apm-agent-go/pull/1434) +* module/apmotel: bump go.opentelemetry.io/otel/metric [#1435](https://github.com/elastic/apm-agent-go/pull/1435) +* module/apmotel: follow APM OTel spec and prefer delta temporality [#1437](https://github.com/elastic/apm-agent-go/pull/1437) +* module/apmotel: set the proper trace ID and span ID in trace context [#1438](https://github.com/elastic/apm-agent-go/pull/1438) +* module/apmotel: handle context flags when creating remote transactions and spans [#1441](https://github.com/elastic/apm-agent-go/pull/1441) + +## 2.4.1 [elastic-apm-go-agent-241-release-notes] +**Release date:** April 27, 2023 + +### Features and enhancements [elastic-apm-go-agent-241-features-enhancements] +* Downgrade OpenTelemetry metrics from v1.15.0-rc.2 to 0.37.0 [#1420](https://github.com/elastic/apm-agent-go/pull/1420) +* Mark OpenTelemetry metrics as technical preview [#1419](https://github.com/elastic/apm-agent-go/pull/1419) + +## 2.4.0 [elastic-apm-go-agent-240-release-notes] +**Release date:** April 26, 2023 + +### Features and enhancements [elastic-apm-go-agent-240-features-enhancements] +* Add bridge to support OpenTelemetry metrics [#1407](https://github.com/elastic/apm-agent-go/pull/1407) +* Add custom SDK support OpenTelemetry traces [#1410](https://github.com/elastic/apm-agent-go/pull/1410) + +## 2.3.0 [elastic-apm-go-agent-230-release-notes] +**Release date:** March 30, 2023 + +### Features and enhancements [elastic-apm-go-agent-230-features-enhancements] +* Ensure minimum retry interval of 5 seconds for fetching central configuration [#1337](https://github.com/elastic/apm-agent-go/pull/1337) +* Update span compression logic to handle `service.target.*` fields [#1339](https://github.com/elastic/apm-agent-go/pull/1339) +* module/apmchiv5: Add panic propogation option [#1359](https://github.com/elastic/apm-agent-go/pull/1359) +* module/apmgormv2: Add sqlserver support [#1356](https://github.com/elastic/apm-agent-go/pull/1356) +* module/apmsql: Add sqlserver support [#1356](https://github.com/elastic/apm-agent-go/pull/1356) +* Update compressed spans to use `service.target.*` fields to derive its name [#1336](https://github.com/elastic/apm-agent-go/pull/1336) +* module/apmpgxv5: new instrumentation module for jackc/pgx v5 with enhanced support e.g. detailed `BATCH` and `CONNECT` traces [#1364](https://github.com/elastic/apm-agent-go/pull/1364) +* Add support for `Unwrap []error` [#1400](https://github.com/elastic/apm-agent-go/pull/1400) + +## 2.2.0 [elastic-apm-go-agent-220-release-notes] +**Release date:** October 31, 2022 + +### Features and enhancements [elastic-apm-go-agent-220-features-enhancements] +* Global labels are now parsed when the tracer is constructed, instead of parsing only once on package initialization [#1290](https://github.com/elastic/apm-agent-go/pull/1290) +* Rename span_frames_min_duration to span_stack_trace_min_duration [#1285](https://github.com/elastic/apm-agent-go/pull/1285) +* Ignore `\*principal\*` headers by default [#1332](https://github.com/elastic/apm-agent-go/pull/1332) +* Add `apmpgx` module for postgres tracing with jackc/pgx driver enhanced support e.g. Copy and Batch statements [#1301](https://github.com/elastic/apm-agent-go/pull/1301) +* Disable same-kind and enable exact-match compression by default [#1256](https://github.com/elastic/apm-agent-go/pull/1256) +* module/apmechov4: add `WithRequestName` option [#1268](https://github.com/elastic/apm-agent-go/pull/1268) +* Added support for adding span links when starting transactions and spans [#1269](https://github.com/elastic/apm-agent-go/pull/1269) +* Added support for the `trace_continuation_strategy` [#1270](https://github.com/elastic/apm-agent-go/pull/1270) +* `transaction.type` and `span.type` are now set to "custom" if an empty string is specified [#1272](https://github.com/elastic/apm-agent-go/pull/1272) +* We now capture the database instance name in `service.target.*`, for improved backend granularity [#1279](https://github.com/elastic/apm-agent-go/pull/1279) +* Improved Kubernetes pod UID and container ID discovery coverage [#1288](https://github.com/elastic/apm-agent-go/pull/1288) +* module/apmgin: add `WithPanicPropagation` option [#1314](https://github.com/elastic/apm-agent-go/pull/1314) +* Exit spans may now have non-exit child spans if they have the same type and subtype [#1320](https://github.com/elastic/apm-agent-go/pull/1320) +* Updated instrumentation modules to mark spans as exit spans where possible [#1317](https://github.com/elastic/apm-agent-go/pull/1317) + +### Fixes [elastic-apm-go-agent-220-fixes] +* module/apmawssdkgo: fixed a panic related to drop spans [#1273](https://github.com/elastic/apm-agent-go/pull/1273) +* Fixed `span.name` for AWS SNS spans to match the spec [#1286](https://github.com/elastic/apm-agent-go/pull/1286) + +## 2.1.0 [elastic-apm-go-agent-210-release-notes] +**Release date:** May 20, 2022 + +### Features and enhancements [elastic-apm-go-agent-210-features-enhancements] +* Replace `authorization` with `*auth*` pattern for sanitizing field names [#1230](https://github.com/elastic/apm-agent-go/pull/1230) +* Fetch initial server version async to prevent blocking NewTracer for 10 seconds [#1239](https://github.com/elastic/apm-agent-go/pull/1239) + +### Fixes [elastic-apm-go-agent-210-fixes] +* Fix race in `apm.DefaultTracer` which could lead to multiple tracers being created [#1248](https://github.com/elastic/apm-agent-go/pull/1248) + +## 2.0.0 [elastic-apm-go-agent-200-release-notes] +**Release date:** March 17, 2022 + +### Features and enhancements [elastic-apm-go-agent-200-features-enhancements] +* Record `transaction.name` on errors [#1177](https://github.com/elastic/apm-agent-go/pull/1177) +* Stop recording unused `transaction.duration.*` and `transaction.breakdown.count` metrics [#1167](https://github.com/elastic/apm-agent-go/pull/1167) +* Make tracestate parsing more lenient, according to W3c spec, allowing duplicate vendor keys [#1183](https://github.com/elastic/apm-agent-go/pull/1183) +* Introduced `transport.NewHTTPTransportOptions` [#1168](https://github.com/elastic/apm-agent-go/pull/1168) +* Change `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` special cases to match agent spec [#1188](https://github.com/elastic/apm-agent-go/pull/1188) +* Remove stacktrace.ContextSetter [#1187](https://github.com/elastic/apm-agent-go/pull/1187) +* Drop support for versions of Go prior to 1.15.0 [#1190](https://github.com/elastic/apm-agent-go/pull/1190) +* Replace apm.DefaultTracer with an initialization function [#1189](https://github.com/elastic/apm-agent-go/pull/1189) +* Remove transport.Default, construct a new Transport in each new tracer [#1195](https://github.com/elastic/apm-agent-go/pull/1195) +* Add service name and version to User-Agent header [#1196](https://github.com/elastic/apm-agent-go/pull/1196) +* Remove WarningLogger, add Warningf methe to Logger [#1205](https://github.com/elastic/apm-agent-go/pull/1205) +* Replace Sampler with ExtendedSampler [#1206](https://github.com/elastic/apm-agent-go/pull/1206) +* Drop unsampled txs when connected to an APM Server >= 8.0 [#1208](https://github.com/elastic/apm-agent-go/pull/1208) +* Removed SetTag [#1218](https://github.com/elastic/apm-agent-go/pull/1218) +* Unexport Tracer’s fields — TracerOptions must be used instead [#1219](https://github.com/elastic/apm-agent-go/pull/1219) + +### Fixes [elastic-apm-go-agent-200-fixes] +* Fix panic in apmgocql [#1180](https://github.com/elastic/apm-agent-go/pull/1180) \ No newline at end of file diff --git a/docs/release-notes/known-issues.md b/docs/release-notes/known-issues.md new file mode 100644 index 000000000..c5ca477af --- /dev/null +++ b/docs/release-notes/known-issues.md @@ -0,0 +1,20 @@ +--- +navigation_title: "Elastic APM Go Agent" + +--- + +# Elastic APM Go Agent known issues [elastic-apm-go-agent-known-issues] + +% Use the following template to add entries to this page. + +% :::{dropdown} Title of known issue +% **Details** +% On [Month/Day/Year], a known issue was discovered that [description of known issue]. + +% **Workaround** +% Workaround description. + +% **Resolved** +% On [Month/Day/Year], this issue was resolved. + +::: \ No newline at end of file diff --git a/docs/release-notes/toc.yml b/docs/release-notes/toc.yml new file mode 100644 index 000000000..3bbe7c829 --- /dev/null +++ b/docs/release-notes/toc.yml @@ -0,0 +1,3 @@ +toc: + - file: index.md + - file: known-issues.md \ No newline at end of file diff --git a/docs/set-up.asciidoc b/docs/set-up.asciidoc deleted file mode 100644 index 3f453e850..000000000 --- a/docs/set-up.asciidoc +++ /dev/null @@ -1,50 +0,0 @@ -[[getting-started]] -== Set up the Agent - -To start reporting your Go application's performance to Elastic APM, you need to do a few things: - -1. <>. -2. <>. -3. <>. - -[float] -[[installation]] -== Install the Agent - -Within a Go module, install the Elastic APM Go agent package using `go get`: - -[source,bash] ----- -go get -u go.elastic.co/apm/v2 ----- - -[float] -=== Requirements - -You can find a list of the supported frameworks and other technologies in the -<> section. - -[float] -[[instrumenting-source]] -== Instrument Go Source Code - -Instrumentation is the process of extending your application's code to report trace data to Elastic APM. -Go applications must be instrumented manually at the source code level. -There are two ways to instrument your applications: - -* Using <>. -* <> and <> with the Go Agent API. - -Where possible, use the built-in modules to report transactions served by web and RPC frameworks in your application. - -[float] -[[configure-setup]] -== Configure the Agent - -include::./configuration.asciidoc[tag=setup-config] - -See <> to learn about all available options. - -include::./instrumenting.asciidoc[] -include::./custom-instrumentation.asciidoc[] -include::./context-propagation.asciidoc[] diff --git a/docs/supported-tech.asciidoc b/docs/supported-tech.asciidoc deleted file mode 100644 index 85d665787..000000000 --- a/docs/supported-tech.asciidoc +++ /dev/null @@ -1,356 +0,0 @@ -[[supported-tech]] -== Supported Technologies - -This page describes the technologies supported by the Elastic APM Go agent. - -If your favorite technology is not supported yet, you start a conversation -in the https://discuss.elastic.co/c/apm[Discuss forum]. - -If you would like to get more involved, take a look at the <>. - -[float] -[[supported-tech-go]] -=== Go - -The Elastic APM Go agent naturally requires Go. We support the last two major -Go releases as described by https://golang.org/doc/devel/release.html#policy[Go's Release Policy]: - -> Each major Go release is supported until there are two newer major releases. -> For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. - -[float] -[[supported-tech-web-frameworks]] -=== Web Frameworks - -We support several third-party web frameworks, as well as Go's standard `net/http` -package. Regardless of the framework, we create a transaction for each incoming -request, and name the transaction after the registered route. - -[float] -==== fasthttp - -We support https://github.com/valyala/fasthttp[valyala/fasthttp], -https://github.com/valyala/fasthttp/releases/tag/v1.26.0[v1.26.0] and greater. - -See <> for more information -about fasthttp instrumentation. - -[float] -==== httprouter - -https://github.com/julienschmidt/httprouter[julienschmidt/httprouter] does -not use semantic versioning, but its API is relatively stable. Any recent -version should be compatible with the Elastic APM Go agent. - -See <> for more -information about httprouter instrumentation. - -[float] -==== Echo - -We support the https://echo.labstack.com/[Echo] web framework, -https://github.com/labstack/echo/releases/tag/3.3.5[v3.3.5] and greater. - -We provide different packages for the Echo v3 and v4 versions: -`module/apmecho` for Echo v3.x, and `module/apmechov4` for Echo v4.x. - -See <> for more information -about Echo instrumentation. - -[float] -==== Gin - -We support the https://gin-gonic.com/[Gin] web framework, -https://github.com/gin-gonic/gin/releases/tag/v1.2[v1.2] and greater. - -See <> for more information -about Gin instrumentation. - - -[float] -==== Fiber - -We support the https://gofiber.io/[Fiber] web framework, -https://github.com/gofiber/fiber/releases/tag/v2.18.0[v2.18.0] and greater. - -We provide package only for the Fiber v2. -See <> for more information -about Fiber instrumentation. - -[float] -==== Beego - -We support the https://beego.me/[Beego] web framework, -https://github.com/astaxie/beego/releases/tag/v1.10.0[v1.10.0] and greater. - -See <> for more information -about Beego instrumentation. - -[float] -==== gorilla/mux - -We support http://www.gorillatoolkit.org/pkg/mux[gorilla/mux] -https://github.com/gorilla/mux/releases/tag/v1.6.1[v1.6.1] and greater. -Older versions are not supported due to the use of gorilla.Middleware. - -See <> for more information -about gorilla/mux instrumentation. - -[float] -==== go-restful - -We support https://github.com/emicklei/go-restful[go-restful], -https://github.com/emicklei/go-restful/releases/tag/2.0.0[2.0.0] and greater. - -See <> for more information -about go-restful instrumentation. - -[float] -==== chi - -We support https://github.com/go-chi/chi[chi], -https://github.com/go-chi/chi/releases/tag/v4.0.0[v4.0.0] and greater. - -See <> for more information -about chi instrumentation. - -[float] -==== negroni - -We support https://github.com/urfave/negroni[negroni], -https://github.com/urfave/negroni/releases/tag/v1.0.0[v1.0.0] and greater. - -See <> for more information -about negroni instrumentation. - -[float] -[[supported-tech-databases]] -=== Databases - -[float] -==== database/sql - -We support tracing requests with any `database/sql` driver, provided -the driver is registered with the Elastic APM Go agent. Spans will be -created for each statemented executed. - -When using one of the following drivers, the Elastic APM Go agent will -be able to parse the datasource name, and provide more context in the -spans it emits: - -- https://github.com/lib/pq[lib/pq] (PostgreSQL) -- https://github.com/jackc/pgx[jackc/pgx] (PostgreSQL) -- https://github.com/go-sql-driver/mysql[go-sql-driver/mysql] -- https://github.com/go-sqlite3[mattn/go-sqlite3] - -See <> for more information -about database/sql instrumentation. - -[float] -==== GORM - -We support the http://gorm.io/[GORM] object-relational mapping library, -https://github.com/jinzhu/gorm/releases/tag/v1.9[v1.9] and greater. -Spans will be created for each create, query, update, and delete -operation. - -As with `database/sql` support we provide additional support for the -postgres, mysql, and sqlite dialects. - -We provide different packages for the Gorm v1 and v2 versions: -`module/apmgorm` for Gorm v1.x, and `module/apmgormv2` for Gorm v2.x. - -See <> or <> for more information -about GORM instrumentation. - -[float] -==== go-pg/pg - -We support the https://github.com/go-pg/pg[go-pg/pg] PostgreSQL ORM, -https://github.com/go-pg/pg/releases/tag/v8.0.4[v8.0.4]. Spans will -be created for each database operation. - -See <> for more information -about go-pg instrumentation. - -[float] -==== Cassandra (gocql) - -https://gocql.github.io/[GoCQL] does not have a stable API, so we will -provide support for the most recent API, and older versions of the API -on a best-effort basis. Spans will be created for each query. When the -batch API is used, a span will be created for the batch, and a sub-span -is created for each query in the batch. - -See <> for more information -about GoCQL instrumentation. - -[float] -==== Redis (gomodule/redigo) - -We support https://github.com/gomodule/redigo[Redigo], -https://github.com/gomodule/redigo/tree/v2.0.0[v2.0.0] and greater. -We provide helper functions for reporting Redis commands as spans. - -See <> for more information -about Redigo instrumentation. - -[float] -==== Redis (go-redis/redis) - -We support https://github.com/go-redis/redis[go-redis], -https://github.com/go-redis/redis/tree/v6.15.3[v6.15.3]. -We provide helper functions for reporting Redis commands as spans. - -See <> for more information -about go-redis instrumentation. - -[float] -==== Elasticsearch - -We provide instrumentation for Elasticsearch clients. This is usable with -the https://github.com/elastic/go-elasticsearch[go-elasticsearch] and -https://github.com/olivere/elastic[olivere/elastic] clients, and should -also be usable with any other clients that provide a means of configuring -the underlying `net/http.RoundTripper`. - -See <> for more -information about Elasticsearch client instrumentation. - -[float] -==== MongoDB - -We provide instrumentation for the official -https://github.com/mongodb/mongo-go-driver[MongoDB Go Driver], -https://github.com/mongodb/mongo-go-driver/releases/tag/v1.0.0[v1.0.0] and -greater. Spans will be created for each MongoDB command executed within a -context containing a transaction. - -See <> for more information about -the MongoDB Go Driver instrumentation. - -[float] -==== DynamoDB - -We provide instrumentation for AWS DynamoDB. This is usable with -https://github.com/aws/aws-sdk-go[AWS SDK Go]. - -See <> for more information -about AWS SDK Go instrumentation. - -[float] -[[supported-tech-rpc]] -=== RPC Frameworks - -[float] -==== gRPC - -We support https://grpc.io/[gRPC] -https://github.com/grpc/grpc-go/releases/tag/v1.3.0[v1.3.0] and greater. -We provide unary and stream interceptors for both the client and server. -The server interceptor will create a transaction for each incoming request, -and the client interceptor will create a span for each outgoing request. - -See <> for more information -about gRPC instrumentation. - -[float] -[[supported-tech-services]] -=== Service Frameworks - -[float] -==== Go kit - -We support tracing https://gokit.io/[Go kit] clients and servers when -using the gRPC or HTTP transport, by way of <> -and <> respectively. - -Code examples are available at https://pkg.go.dev/go.elastic.co/apm/module/apmgokit/v2 -for getting started. - -[float] -[[supported-tech-logging]] -=== Logging frameworks - -[float] -==== Logrus - -We support log correlation and exception tracking with -https://github.com/sirupsen/logrus/[Logrus], -https://github.com/sirupsen/logrus/releases/tag/v1.1.0[v1.1.0] and greater. - -See <> for more information -about Logrus integration. - -[float] -==== Zap - -We support log correlation and exception tracking with -https://github.com/uber-go/zap/[Zap], -https://github.com/uber-go/zap/releases/tag/v1.0.0[v1.0.0] and greater. - -See <> for more information -about Zap integration. - -[float] -==== Zerolog - -We support log correlation and exception tracking with -https://github.com/rs/zerolog/[Zerolog], -https://github.com/rs/zerolog/releases/tag/v1.12.0[v1.12.0] and greater. - -See <> for more information -about Zerolog integration. - -[float] -==== Slog - -We support log correlation and error tracking with -https://pkg.go.dev/log/slog/[Slog], -https://pkg.go.dev/log/slog@go1.21.0/[v1.21.0] and greater. - -See <> for more information -about slog integration. - -[float] -[[supported-tech-object-storage]] -=== Object Storage - -[float] -==== Amazon S3 -We provide instrumentation for AWS S3. This is usable with -https://github.com/aws/aws-sdk-go[AWS SDK Go]. - -See <> for more information -about AWS SDK Go instrumentation. - -[float] -==== Azure Storage -We provide instrumentation for Azure Storage. This is usable with: - -- github.com/Azure/azure-storage-blob-go/azblob[Azure Blob Storage] -- github.com/Azure/azure-storage-queue-go/azqueue[Azure Queue Storage] -- github.com/Azure/azure-storage-file-go/azfile[Azure File Storage] - -See <> for more information -about Azure SDK Go instrumentation. - -[float] -[[supported-tech-messaging-systems]] -=== Messaging Systems - -[float] -==== Amazon SQS -We provide instrumentation for AWS SQS. This is usable with -https://github.com/aws/aws-sdk-go[AWS SDK Go]. - -See <> for more information -about AWS SDK Go instrumentation. - -[float] -==== Amazon SNS -We provide instrumentation for AWS SNS. This is usable with -https://github.com/aws/aws-sdk-go[AWS SDK Go]. - -See <> for more information -about AWS SDK Go instrumentation. diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc deleted file mode 100644 index f79730571..000000000 --- a/docs/troubleshooting.asciidoc +++ /dev/null @@ -1,54 +0,0 @@ -[[troubleshooting]] -== Troubleshooting - -Is something not working as expected? -Don't worry if you can't figure out what the problem is; we’re here to help! -First, ensure your app is compatible with the agent's <>. - -If you're an existing Elastic customer with a support contract, please create a ticket in the -https://support.elastic.co/customers/s/login/[Elastic Support portal]. -Other users can post in the https://discuss.elastic.co/c/apm[APM discuss forum]. - -IMPORTANT: *Please upload your complete debug logs* to a service like https://gist.github.com[GitHub Gist] -so that we can analyze the problem. -Logs should include everything from when the application starts up until the first request executes. -Instructions for enabling logging are below. - -[float] -[[agent-logging]] -=== Logging - -Agent logs are critical to the debugging process. -By default, this logging is disabled. To enable it, set a log output file with <>. -Alternatively, if you're using Docker or Kubernetes and are okay with mixing agent and application logs, -you can set `ELASTIC_APM_LOG_FILE=stderr`. - -NOTE: The agent does not rotate log files. Log rotation must be handled externally. - -With logging enabled, use <> to increase the granularity of the agent's logging. -For example: `ELASTIC_APM_LOG_LEVEL=debug`. - -Be sure to execute a few requests to your application before posting your log files. -Each request should add lines similar to these in the logs: - -[source,log] ----- -{"level":"debug","time":"2020-07-23T11:46:32+08:00","message":"sent request with 100 transactions, 0 spans, 0 errors, 0 metricsets"} ----- - -If you don't see lines like these, it's likely that you haven't instrumented your application correctly. - -[float] -[[disable-agent]] -=== Disable the Agent - -In the unlikely event the agent causes disruptions to a production application, -you can disable the agent while you troubleshoot. - -If you have access to <>, -you can disable the recording of events by setting <> to `false`. -When changed at runtime from a supported source, there's no need to restart your application. - -If that doesn't work, or you don't have access to dynamic configuration, you can disable the agent by setting -<> to `false`. -Restart your application for the changes to apply. diff --git a/docs/upgrading.asciidoc b/docs/upgrading.asciidoc deleted file mode 100644 index 18885ec54..000000000 --- a/docs/upgrading.asciidoc +++ /dev/null @@ -1,18 +0,0 @@ -[[upgrading]] -== Upgrading -Upgrades between minor versions of the agent, like from 1.1 to 1.2 are always backwards compatible. -Upgrades that involve a major version bump often come with some backwards incompatible changes. - -Before upgrading the agent, be sure to review the: - -* <> -* {apm-guide-ref}/agent-server-compatibility.html[Agent and Server compatibility chart] - -[float] -[[end-of-life-dates]] -=== End of life dates - -We love all our products, but sometimes we must say goodbye to a release so that we can continue moving -forward on future development and innovation. -Our https://www.elastic.co/support/eol[End of life policy] defines how long a given release is considered supported, -as well as how long a release is considered still in active development or maintenance.