github.com/mier85/go-sensor@v1.30.1-0.20220920111756-9bf41b3bc7e0/README.md (about) 1 # Instana Go Collector 2 3  4 5 [](https://circleci.com/gh/instana/go-sensor/tree/master) 6 [][pkg.go.dev] 7 [](http://opentracing.io) 8 [](https://goreportcard.com/report/github.com/mier85/go-sensor) 9 10 The Go Collector is a runtime metrics collector, code execution tracer and profiler for applications and services written in Go. This module 11 is a part of [Instana](https://instana.com) APM solution. 12 13 The Go Collector requires Go version 1.9 or greater. 14 15 ## Installation 16 17 To add Instana Go Collector to your service run: 18 19 ```bash 20 $ go get github.com/mier85/go-sensor 21 ``` 22 23 You might also consider installing [supplemental modules](https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#supported-frameworks-and-libraries) 24 that provide instrumentation for most popular 3rd-party packages. 25 26 Please refer to [Instana Go Collector documentation][docs.installation] for further details on how to activate Go Collector and use it to 27 instrument your application code. 28 29 ## Configuration 30 31 The Go Collector accepts both configuration from within the application code and via environment variables. The values provided via enironment 32 variables take precedence. In case is no specific configuration provided, the values returned by 33 [instana.DefaultOptions()][instana.DefaultOptions] will be used. 34 35 Please refer to [Go Collector Configuration page][docs.configuration] for detailed instructions. There is also the 36 [Go Collector How To page][docs.howto.configuration] that covers the most common configuration use cases. 37 38 ## Usage 39 40 In order to trace the code execution, a few minor changes to your app's source code is needed. Please check the [examples section](#examples) 41 and the [Go Collector How To guide][docs.howto.instrumentation] to learn about common instrumentation patterns. 42 43 ## Features 44 45 ### Runtime metrics collection 46 47 Once [initialized](https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#how-to-initialize-go-collector), the Go Collector starts automatically 48 collecting and sending the following runtime metrics to Instana in background: 49 50 * Memory usage 51 * Heap usage 52 * GC activity 53 * Goroutines 54 55 ### Code execution tracing 56 57 Instana Go Collector provides an API to [instrument][docs.howto.instrumentation] function and method calls from within the application code 58 to trace its execution. 59 60 The core `github.com/mier85/go-sensor` package is shipped with instrumentation wrappers for the standard library, including HTTP client and 61 server, as well as SQL database drivers compatible with `database/sql`. There are also supplemental 62 [instrumentation modules](https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#supported-frameworks-and-libraries) provide code wrappers to instrument 63 the most popular 3rd-party libraries. 64 65 Please check the [examples section](#examples) and the [Go Collector How To guide][docs.howto.instrumentation] to learn about common 66 instrumentation patterns. 67 68 #### OpenTracing 69 70 Instana Go Collector provides an interface compatible with [`github.com/opentracing/opentracing-go`](https://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](./instrumentation) 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. 71 72 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. 73 74 ### Trace continuation and propagation 75 76 Instana Go Collector ensures that application trace context will continued and propagated beyond the service boundaries using various 77 methods, depending on the technology being used. Alongside with Instana-specific HTTP headers or message attributes, a number of open 78 standards are supported, such as W3C Trace Context and OpenTelemetry. 79 80 #### W3C Trace Context & OpenTelemetry 81 82 The instrumentation wrappers provided with Go Collector automatically inject and extract trace context provided via W3C Trace Context HTTP 83 headers. 84 85 ### Continuous profiling 86 87 [Instana AutoProfile™][docs.autoprofile] generates and reports process profiles to Instana. Unlike development-time and on-demand profilers, 88 where a user must manually initiate profiling, AutoProfile™ automatically schedules and continuously performs profiling appropriate for 89 critical production environments. 90 91 Please refer to the [Instana Go Collector docs](https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#instana-autoprofile%E2%84%A2) to learn how to activate and 92 use continuous profiling for your applications and services. 93 94 ### Sending custom events 95 96 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](https://www.ibm.com/docs/en/obi/current?topic=integrations-sdks-apis). 97 98 To learn more, see the [Events API](./EventAPI.md) document in this repository. 99 100 ## Examples 101 102 Following examples are included in the `example` folder: 103 104 * [Greeter](./example/http-database-greeter) - an instrumented HTTP server that queries a database 105 * [Doubler](./example/kafka-producer-consumer) - an instrumented Kafka processor, that consumes and produces messages 106 * [Event](./example/event) - Demonstrates usage of the Events API 107 * [Autoprofile](./example/autoprofile) - Demonstrates usage of the AutoProfile™ 108 * [OpenTracing](./example/opentracing) - an example of usage of Instana tracer in an app instrumented with OpenTracing 109 * [gRPC](./example/grpc-client-server) - an example of usage of Instana tracer in an app instrumented with gRPC 110 * [Gin](./example/gin) - an example of usage of Instana tracer instrumenting a [`Gin`](github.com/gin-gonic/gin) application 111 * [httprouter](./example/httprouter) - an example of usage of Instana tracer instrumenting a [`github.com/julienschmidt/httprouter`](https://github.com/julienschmidt/httprouter) router 112 113 For more examples please consult the [godoc][godoc] and the [Go Collector How To page](https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations). 114 115 ## Filing Issues 116 117 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](https://support.instana.com/hc/requests/new) instead. 118 119 <!-- Links section --> 120 121 [godoc]: https://pkg.go.dev/github.com/mier85/go-sensor/?tab=doc#pkg-examples 122 [pkg.go.dev]: https://pkg.go.dev/github.com/mier85/go-sensor 123 [docs.autoprofile]: https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#instana-autoprofile%E2%84%A2 124 [docs.configuration]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-configuration 125 [docs.installation]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-installation 126 [docs.howto.configuration]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#configuration 127 [docs.howto.instrumentation]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#instrumentation 128 [instana.DefaultOptions]: https://pkg.go.dev/github.com/mier85/go-sensor#DefaultOptions