Categorygithub.com/mier85/go-sensor
modulepackage
0.2.0
Repository: https://github.com/mier85/go-sensor.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
42
Dependents
6
Files
6.3k SLOC

# README

Instana Go Collector

Instana, an IBM company

Build Status PkgGoDev OpenTracing Go Report Card

The Go Collector is a runtime metrics collector, code execution tracer and profiler for applications and services written in Go. This module is a part of Instana APM solution.

The Go Collector requires Go version 1.9 or greater.

Installation

To add Instana Go Collector to your service run:

$ go get github.com/mier85/go-sensor

You might also consider installing supplemental modules that provide instrumentation for most popular 3rd-party packages.

Please refer to Instana Go Collector documentation for further details on how to activate Go Collector and use it to instrument your application code.

Configuration

The Go Collector accepts both configuration from within the application code and via environment variables. The values provided via enironment variables take precedence. In case is no specific configuration provided, the values returned by instana.DefaultOptions() will be used.

Please refer to Go Collector Configuration page for detailed instructions. There is also the Go Collector How To page that covers the most common configuration use cases.

Usage

In order to trace the code execution, a few minor changes to your app's source code is needed. Please check the examples section and the Go Collector How To guide to learn about common instrumentation patterns.

Features

Runtime metrics collection

Once initialized, the Go Collector starts automatically collecting and sending the following runtime metrics to Instana in background:

  • Memory usage
  • Heap usage
  • GC activity
  • Goroutines

Code execution tracing

Instana Go Collector provides an API to instrument function and method calls from within the application code to trace its execution.

The core github.com/mier85/go-sensor package is shipped with instrumentation wrappers for the standard library, including HTTP client and server, as well as SQL database drivers compatible with database/sql. There are also supplemental instrumentation modules provide code wrappers to instrument the most popular 3rd-party libraries.

Please check the examples section and the Go Collector How To guide to learn about common instrumentation patterns.

OpenTracing

Instana Go Collector provides an interface compatible with github.com/opentracing/opentracing-go and thus can be used as a global tracer. However, the recommended approach is to use the Instana wrapper packages/functions provided in the library. They set up a lot of semantic information which helps Instana get the best picture of the application possible. Sending proper tags is especially important when it comes to correlating calls to infrastructure and since they are strings mostly, there is a large room for making a mistake.

The Go Collector will remap OpenTracing HTTP headers into Instana headers, so parallel use with some other OpenTracing model is not possible. The Instana tracer is based on the OpenTracing Go basictracer with necessary modifications to map to the Instana tracing model.

Trace continuation and propagation

Instana Go Collector ensures that application trace context will continued and propagated beyond the service boundaries using various methods, depending on the technology being used. Alongside with Instana-specific HTTP headers or message attributes, a number of open standards are supported, such as W3C Trace Context and OpenTelemetry.

W3C Trace Context & OpenTelemetry

The instrumentation wrappers provided with Go Collector automatically inject and extract trace context provided via W3C Trace Context HTTP headers.

Continuous profiling

Instana AutoProfile™ generates and reports process profiles to Instana. Unlike development-time and on-demand profilers, where a user must manually initiate profiling, AutoProfile™ automatically schedules and continuously performs profiling appropriate for critical production environments.

Please refer to the Instana Go Collector docs to learn how to activate and use continuous profiling for your applications and services.

Sending custom events

The Go Collector, be it instantiated explicitly or implicitly through the tracer, provides a simple wrapper API to send events to Instana as described in its documentation.

To learn more, see the Events API document in this repository.

Examples

Following examples are included in the example folder:

  • Greeter - an instrumented HTTP server that queries a database
  • Doubler - an instrumented Kafka processor, that consumes and produces messages
  • Event - Demonstrates usage of the Events API
  • Autoprofile - Demonstrates usage of the AutoProfile™
  • OpenTracing - an example of usage of Instana tracer in an app instrumented with OpenTracing
  • gRPC - an example of usage of Instana tracer in an app instrumented with gRPC
  • Gin - an example of usage of Instana tracer instrumenting a Gin application
  • httprouter - an example of usage of Instana tracer instrumenting a github.com/julienschmidt/httprouter router

For more examples please consult the godoc and the Go Collector How To page.

Filing Issues

If something is not working as expected or you have a question, instead of opening an issue in this repository, please open a ticket at Instana Support portal instead.

# Packages

Package acceptor provides marshaling structs for Instana serverless acceptor API.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

BatchSize returns an opentracing.Tag to mark the span as a batched span representing similar span categories.
ContextWithSpan returns a new context.Context holding a reference to an active span.
DefaultOptions returns the default set of options to configure Instana sensor.
DefaultSecretsMatcher returns the default secrets matcher, that matches strings containing "key", "password" and "secret" ignoring the case.
DefaultTracerOptions returns the default set of options to configure a tracer.
EumSnippet generates javascript code to initialize JavaScript agent Deprecated: this snippet is outdated and this method will be removed in the next major version.
Flush forces Instana collector to send all buffered data to the agent.
FormatID converts an Instana ID to a value that can be used in context propagation (such as HTTP headers).
FormatLongID converts a 128-bit Instana ID passed in two quad words to an unsigned hex string suitable for context propagation.
Header2ID calls instana.ParseID() and returns its result.
ID2Header calls instana.FormatID() and returns its result and a nil error.
InitSensor intializes the sensor (without tracing) to begin collecting and reporting metrics.
InstrumentSQLDriver instruments provided database driver for use with `sql.Open()`.
NamedMatcher returns a secrets matcher supported by Instana host agent configuration See https://www.instana.com/docs/setup_and_manage/host_agent/configuration/#secrets.
NewRecorder initializes a new span recorder.
NewRootSpanContext initializes a new root span context issuing a new trace ID.
NewSensor creates a new instana.Sensor.
NewSensorWithTracer returns a new instana.Sensor that uses provided tracer to report spans.
NewSpanContext initializes a new child span context from its parent.
NewSpanData initializes a new span data from tracer span.
NewTestRecorder initializes a new span recorder that keeps all collected until they are requested.
NewTracer initializes a new tracer with default options.
NewTracerWithEverything initializes and configures a new tracer.
NewTracerWithOptions initializes and configures a new tracer that collects and sends spans to the agent.
ParseID converts an header context value into an Instana ID.
ParseLongID converts an header context value into a 128-bit Instana ID.
Ready returns whether the Instana collector is ready to collect and send data to the agent.
RecorderWithFlushInterval lets you specify how often traces should be flushed.
RecorderWithQueueWhenNotReady will enable queuing even when the sensor is not yet ready.
RoundTripper wraps an existing http.RoundTripper and injects the tracing headers into the outgoing request.
SendDefaultServiceEvent sends a default event which already contains the service and host.
SendHostEvent sends an event on the current host.
SendServiceEvent sends an event on a specific service.
SetLogger configures the default logger to be used by Instana go-sensor.
SpanFromContext retrieves previously stored active span from context.
SQLInstrumentAndOpen returns instrumented `*sql.DB`.
SQLOpen is a convenience wrapper for `sql.Open()` to use the instrumented version of a driver previosly registered using `instana.InstrumentSQLDriver()`.
SuppressTracing returns an opentracing.Tag to mark the span and any of its child spans as not to be sent to the agent.
TracingHandlerFunc is an HTTP middleware that captures the tracing data and ensures trace context propagation via OpenTracing headers.
TracingNamedHandlerFunc is an HTTP middleware that similarly to instana.TracingHandlerFunc() captures the tracing data, while allowing to provide a unique route indetifier to be associated with each request.
WrapSQLConnector wraps an existing sql.Connector and instruments the DB calls made using it.

# Constants

AWS DynamoDB client span.
AWS Lambda entry span.
AWS Lambda invoke span.
AWS S3 client span.
AWS SNS client span.
AWS SQS client span.
ContainsIgnoreCaseMatcher matches the substring in a string ignoring the case.
ContainsMatcher matches the substring in a string.
Valid log levels.
DefaultForceSpanSendAt is the default max number of spans to buffer before force sending them to the agent.
DefaultMaxBufferedSpans is the default span buffer size.
The kind of a span associated with an inbound call, this must be the first span in the trace.
EqualsIgnoreCaseMatcher matches the string exactly ignoring the case.
EqualsMatcher matches the string exactly.
Valid log levels.
The kind of a span associated with an outbound call, e.g.
FieldB OT Baggage header.
FieldL Level header.
FieldS Span ID header.
FieldSynthetic if set to 1, marks the call as synthetic, e.g.
FieldT Trace ID header.
Google Cloud PubSub client span.
Google Cloud Storage client span.
Registered types supported by Instana.
HTTP server and client spans.
Valid log levels.
The default kind for a span that is associated with a call within the same service.
Kafka consumer/producer span.
Logging span.
MaxLogsPerSpan The maximum number of logs allowed on a span.
MongoDB client span.
NoneMatcher does not match any string.
PostgreSQL client span.
RabbitMQ client span.
Redis client span.
RegexpMatcher matches the string using a set of regular expressions.
Registered types supported by Instana.
RPC server and client spans.
SDK span, a generic span containing arbitrary data.
Defaults for the Event API.
Defaults for the Event API.
Severity values for events sent to the instana agent.
Severity values for events sent to the instana agent.
Severity values for events sent to the instana agent.
SnapshotPeriod is the amount of time in seconds between snapshot reports.
Version is the version of Instana sensor.
Valid log levels.

# Variables

ErrAgentNotReady is an error returned for an attempt to communicate with an agent before the client announcement process is done.

# Structs

AWSDynamoDBSpanData represents the `data` section of a AWS DynamoDB span sent within an OT span document.
AWSDynamoDBSpanTags contains fields within the `data.sns` section of an OT span document.
AWSInvokeSpanTags contains fields within the `aws.lambda.invoke` section of an OT span document.
AWSLambdaCloudWatchEventTags contains fields within the `data.lambda.cw.events` section of an OT span document.
AWSLambdaCloudWatchLogsTags contains fields within the `data.lambda.cw.logs` section of an OT span document.
AWSLambdaCloudWatchSpanTags contains fields within the `data.lambda.cw` section of an OT span document.
AWSLambdaInvokeSpanData represents the `data` section of a AWS Invoke span sent within an OT span document.
AWSLambdaS3SpanTags contains fields within the `data.lambda.s3` section of an OT span document.
AWSLambdaSpanData is the base span data type for AWS Lambda entry spans.
AWSLambdaSpanTags contains fields within the `data.lambda` section of an OT span document.
AWSLambdaSQSSpanTags contains fields within the `data.lambda.sqs` section of an OT span document.
AWSS3EventTags represens metadata for an S3 event.
AWSS3SpanData represents the `data` section of a AWS S3 span sent within an OT span document.
AWSS3SpanTags contains fields within the `data.s3` section of an OT span document.
AWSSNSSpanData represents the `data` section of a AWS SNS span sent within an OT span document.
AWSSNSSpanTags contains fields within the `data.sns` section of an OT span document.
AWSSQSMessageTags represents span tags for an SQS message delivery.
AWSSQSSpanData represents the `data` section of a AWS SQS span sent within an OT span document.
AWSSQSSpanTags contains fields within the `data.sqs` section of an OT span document.
CustomSpanData holds user-defined span tags.
EUMCorrelationData represents the data sent by the Instana End-User Monitoring script integrated into frontend.
EventData is the construct serialized for the host agent.
GCPPubSubSpanData represents the `data` section of a Google Cloud Pub/Sub span sent within an OT span document.
GCPPubSubSpanTags contains fields within the `data.gcps` section of an OT span document.
GCPStorageSpanData represents the `data` section of a Google Cloud Storage span sent within an OT span document.
GCPStorageSpanTags contains fields within the `data.gcs` section of an OT span document.
HTTPSpanData represents the `data` section of an HTTP span sent within an OT span document.
HTTPSpanTags contains fields within the `data.http` section of an OT span document.
KafkaSpanData represents the `data` section of an Kafka span sent within an OT span document.
KafkaSpanTags contains fields within the `data.kafka` section of an OT span document.
LogSpanData represents the `data` section of a logging span.
LogSpanTags contains fields within the `data.log` section of an OT span document.
MongoDBSpanData represents the `data` section of a MongoDB client span.
MongoDBSpanTags contains fields within the `data.mongo` section of an OT span document.
Options allows the user to configure the to-be-initialized sensor.
PostgreSQLSpanData represents the `data` section of a PostgreSQL client span.
RabbitMQSpanData represents the `data` section of an RabbitMQ span.
RabbitMQSpanTags contains fields within the `data.rabbitmq` section.
Recorder accepts spans, processes and queues them for delivery to the backend.
RedisSpanData represents the `data` section of a Redis client span.
RedisSpanTags contains fields within the `data.redis` section of an OT span document.
RPCSpanData represents the `data` section of an RPC span sent within an OT span document.
RPCSpanTags contains fields within the `data.rpc` section of an OT span document.
SDKSpanData represents the `data` section of an SDK span sent within an OT span document.
SDKSpanTags contains fields within the `data.sdk` section of an OT span document.
Sensor is used to inject tracing information into requests.
SnapshotCollector returns a snapshot of Go runtime.
Span represents the OpenTracing span document to be sent to the agent.
SpanContext holds the basic Span metadata.
SpanData contains fields to be sent in the `data` section of an OT span document.
SpanReference is a reference to a span, possibly belonging to another trace, that is relevant to the span context.
TraceReference is used to reference a parent span.
TracerOptions carry the tracer configuration.

# Interfaces

LeveledLogger is an interface of a generic logger that support different message levels.
Matcher verifies whether a string meets predefined conditions.
A SpanRecorder handles all of the `RawSpan` data generated via an associated `Tracer` (see `NewStandardTracer`) instance.
Tracer extends the opentracing.Tracer interface.

# Type aliases

ContextSensitiveFunc is a SpanSensitiveFunc that also takes context.Context Deprecated: use instana.ContextWithSpan() and instana.SpanFromContext() to inject and retrieve spans.
EntityData struct to hold snapshot data.
MemoryS struct to hold snapshot data.
MetricsS struct to hold snapshot data.
RecorderOption lets you specify more options for the recorder.
RegisteredSpanType represents the span type supported by Instana.
SnapshotS struct to hold snapshot data.
SpanKind represents values of field `k` in OpenTracing span representation.
SpanSensitiveFunc is a function executed within a span context Deprecated: use instana.ContextWithSpan() and instana.SpanFromContext() to inject and retrieve spans.