Skip to content

Commit cb65851

Browse files
willianpcsanojsubran
willianpc
and
sanojsubran
authored
README documentation refactoring (#476)
* Refactored README.md documentation --------- Co-authored-by: sanoj subran <[email protected]>
1 parent cf36533 commit cb65851

File tree

12 files changed

+638
-78
lines changed

12 files changed

+638
-78
lines changed

Diff for: ‎README.md

+157-73
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,206 @@
1-
# Instana Go Collector
1+
# IBM Instana Go Tracer
22

3-
![Instana, an IBM company](https://user-images.githubusercontent.com/203793/135623131-0babc5b4-7599-4511-8bf0-ce05922de8a3.png)
4-
5-
[![Build Status](https://circleci.com/gh/instana/go-sensor/tree/master.svg?style=svg)](https://circleci.com/gh/instana/go-sensor/tree/main)
3+
[![Build Status](https://circleci.com/gh/instana/go-sensor/tree/main.svg?style=svg)](https://circleci.com/gh/instana/go-sensor/tree/main)
64
[![PkgGoDev](https://pkg.go.dev/badge/github.com/instana/go-sensor)][pkg.go.dev]
75
[![OpenTracing](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)
86
[![Go Report Card](https://goreportcard.com/badge/github.com/instana/go-sensor)](https://goreportcard.com/report/github.com/instana/go-sensor)
97

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.
8+
The IBM Instana Go Tracer is an SDK that collects traces, metrics, logs and provides profiling for Go applications. The tracer is part of the [IBM Instana Observability](https://www.ibm.com/products/instana) tool set.
9+
10+
## Compatibility
11+
12+
|Tracer Version | Go version |
13+
|-----|-----|
14+
|Up to v1.46.0|v1.9.0 and higher|
15+
|v1.47.0 and higher|v1.13.0 and higher|
1216

13-
## Dependency
14-
- Since version 1.47 the Go Collector requires Go version 1.13 or later.
15-
- Since version 1.53.0, the Go Collector uses fsm v1.0.1 internally. Customers using fsm version prior to v1 in their projects may face compilation issues and will need to update the fsm version to v1.
17+
> [!NOTE]
18+
> Make sure to always use the latest version of the tracer, as it provides new features, improvements, security updates and fixes.
19+
20+
> [!IMPORTANT]
21+
> Since v1.53.0, the Go Tracer uses fsm v1.0.1 internally. Customers using fsm prior to v1 in their projects will need to update it to v1.
1622
1723
## Installation
1824

19-
To add Instana Go Collector to your service run:
25+
To add the tracer to your project, run:
2026

2127
```bash
22-
$ go get github.com/instana/go-sensor
28+
go get -u github.com/instana/go-sensor@latest
2329
```
2430

25-
You might also consider installing [supplemental modules](https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#supported-frameworks-and-libraries)
26-
that provide instrumentation for most popular 3rd-party packages.
31+
> [!NOTE]
32+
> As a good practice, add this command to your CI pipeline or your automated tool before building the application to keep the tracer up to date.
2733
28-
Please refer to [Instana Go Collector documentation][docs.installation] for further details on how to activate Go Collector and use it to
29-
instrument your application code.
34+
## Usage
3035

31-
## Configuration
36+
### Initial Setup
3237

33-
The Go Collector accepts both configuration from within the application code and via environment variables. The values provided via enironment
34-
variables take precedence. In case is no specific configuration provided, the values returned by
35-
[instana.DefaultOptions()][instana.DefaultOptions] will be used.
38+
Once the tracer is added to the project, import the package into the entrypoint file of your application:
3639

37-
Please refer to [Go Collector Configuration page][docs.configuration] for detailed instructions. There is also the
38-
[Go Collector How To page][docs.howto.configuration] that covers the most common configuration use cases.
40+
```go
41+
import (
42+
...
43+
instana "github.com/instana/go-sensor"
44+
)
45+
```
3946

40-
## Usage
47+
Create a reference to the collector and initialize it with a service name:
4148

42-
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)
43-
and the [Go Collector How To guide][docs.howto.instrumentation] to learn about common instrumentation patterns.
49+
```go
50+
var (
51+
...
52+
col instana.TracerLogger
53+
)
4454

45-
## Features
55+
func init() {
56+
...
57+
col = instana.InitCollector(&instana.Options{
58+
Service: "My app",
59+
})
60+
}
61+
```
4662

47-
### Runtime metrics collection
63+
> [!NOTE]
64+
> The tracer expects the Instana Agent to be up and running in the default port 42699. You can change the port with the environment variable ``INSTANA_AGENT_PORT``.
4865
49-
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
50-
collecting and sending the following runtime metrics to Instana in background:
66+
> [!NOTE]
67+
> For non default options, like the Agent host and port, the tracer can be configured either via SDK options, environment variables or Agent options.
5168
52-
* Memory usage
53-
* Heap usage
54-
* GC activity
55-
* Goroutines
69+
### Collecting Metrics
5670

57-
### Code execution tracing
71+
Once the collector has been initialized with `instana.InitCollector`, application metrics such as memory, CPU consumption, active goroutine count etc will be automatically collected and reported to the Agent without further actions or configurations to the SDK.
72+
This data is then already available in the dashboard.
5873

59-
Instana Go Collector provides an API to [instrument][docs.howto.instrumentation] function and method calls from within the application code
60-
to trace its execution.
74+
### Tracing Calls
6175

62-
The core `github.com/instana/go-sensor` package is shipped with instrumentation wrappers for the standard library, including HTTP client and
63-
server, as well as SQL database drivers compatible with `database/sql`. There are also supplemental
64-
[instrumentation modules](https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#supported-frameworks-and-libraries) provide code wrappers to instrument
65-
the most popular 3rd-party libraries.
76+
Let's collect traces of calls received by an HTTP server.
6677

67-
Please check the [examples section](#examples) and the [Go Collector How To guide][docs.howto.instrumentation] to learn about common
68-
instrumentation patterns.
78+
Before any changes, your code should look something like this:
6979

70-
#### OpenTracing
80+
```go
81+
// endpointHandler is the standard http.Handler function
82+
http.HandleFunc("/endpoint", endpointHandler)
7183

72-
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.
84+
log.Fatal(http.ListenAndServe(":9090", nil))
85+
```
7386

74-
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.
87+
Wrap the `endpointHandler` function with `instana.TracingHandlerFunc`. Now your code should look like this:
88+
89+
```go
90+
// endpointHandler is now wrapped by `instana.TracingHandlerFunc`
91+
http.HandleFunc("/endpoint", instana.TracingHandlerFunc(col, "/endpoint", endpointHandler))
92+
93+
log.Fatal(http.ListenAndServe(":9090", nil))
94+
```
95+
96+
When running the application, every time `/endpoint` is called, the tracer will collect this data and send it to the Instana Agent.
97+
You can monitor traces to this endpoint in the Instana UI.
98+
99+
### Profiling
100+
101+
Unlike metrics, profiling needs to be enabled with the `EnableAutoProfile` option, as seen here:
102+
103+
```go
104+
col = instana.InitCollector(&instana.Options{
105+
Service: "My app",
106+
EnableAutoProfile: true,
107+
})
108+
```
75109

76-
### Trace continuation and propagation
110+
You should be able to see your application profiling in the Instana UI under Analytics/Profiles.
77111

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

82-
#### W3C Trace Context & OpenTelemetry
114+
In terms of logging, the SDK provides two distinct logging features:
83115

84-
The instrumentation wrappers provided with Go Collector automatically inject and extract trace context provided via W3C Trace Context HTTP
85-
headers.
116+
1. Traditional logging, that is, logs reported to the standard output, usually used for debugging purposes
117+
1. Instana logs, a feature that allows customers to report logs to the dashboard under Analytics/Logs
86118

87-
### Continuous profiling
119+
#### Traditional Logging
88120

89-
[Instana AutoProfile™][docs.autoprofile] generates and reports process profiles to Instana. Unlike development-time and on-demand profilers,
90-
where a user must manually initiate profiling, AutoProfile™ automatically schedules and continuously performs profiling appropriate for
91-
critical production environments.
121+
Many logs are provided by the SDK, usually prefixed with "INSTANA" and are useful to understand what the tracer is doing underneath. It can also be used for debugging and troubleshoot reasons.
122+
Customers can also provide logs by calling one of the following: [Collector.Info()](https://pkg.go.dev/github.com/instana/go-sensor#Collector.Info), [Collector.Warn()](https://pkg.go.dev/github.com/instana/go-sensor#Collector.Warn), [Collector.Error()](https://pkg.go.dev/github.com/instana/go-sensor#Collector.Error), [Collector.Debug()](https://pkg.go.dev/github.com/instana/go-sensor#Collector.Debug). You can setup the log level via options or the `INSTANA_LOG_LEVEL` environment variable.
123+
124+
You can find detailed information in the [Instana documentation](https://www.ibm.com/docs/en/instana-observability/current?topic=technologies-monitoring-go#tracers-logs).
125+
126+
#### Instana Logs
127+
128+
Instana Logs are spans of the type `log.go` that are rendered in a special format in the dashboard.
129+
You can create logs and report them to the agent or attach them as children of an existing span.
130+
131+
The code snippet below shows how to create logs and send them to the agent:
132+
133+
```go
134+
col := instana.InitCollector(&instana.Options{
135+
Service: "My Go App",
136+
})
137+
138+
col.StartSpan("log.go", []ot.StartSpanOption{
139+
ot.Tags{
140+
"log.level": "error", // available levels: info, warn, error, debug
141+
"log.message": "error from log.go span",
142+
},
143+
}...).Finish() // make sure to "finish" the span, so it's sent to the agent
144+
```
145+
146+
This log can then be visualized in the dashboard under Analytics/Logs. You can add a filter by service name. In our example, the service name is "My Go App".
147+
148+
### Complete Example
149+
150+
[Basic Usage](./example/basic_usage/main.go)
151+
```go
152+
package main
153+
154+
import (
155+
"log"
156+
"net/http"
157+
158+
instana "github.com/instana/go-sensor"
159+
)
160+
161+
func main() {
162+
col := instana.InitCollector(&instana.Options{
163+
Service: "Basic Usage",
164+
EnableAutoProfile: true,
165+
})
166+
167+
http.HandleFunc("/endpoint", instana.TracingHandlerFunc(col, "/endpoint", func(w http.ResponseWriter, r *http.Request) {
168+
w.WriteHeader(http.StatusOK)
169+
}))
170+
171+
log.Fatal(http.ListenAndServe(":7070", nil))
172+
}
173+
```
92174

93-
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
94-
use continuous profiling for your applications and services.
175+
### Wrapping up
95176

96-
### Sending custom events
177+
Let's quickly summarize what we have seen so far:
97178

98-
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).
179+
1. We learned how to install, import and initialize the Instana Go Tracer.
180+
1. Once the tracer is initialized, application metrics are collected out of the box.
181+
1. Application profiling can be enabled via the `EnableAutoProfile` option.
182+
1. Tracing incoming HTTP requests by wrapping the Go standard library `http.Handler` with `instana.TracingHandlerFunc`.
99183

100-
To learn more, see the [Events API](./EventAPI.md) document in this repository.
184+
With this knowledge it's already possible to make your Go application traceable by our SDK.
185+
But there is much more you can do to enhance tracing for your application.
101186

102-
## Examples
187+
The basic functionality covers tracing for the following standard Go features:
103188

104-
Following examples are included in the `example` folder:
189+
1. HTTP incoming requests
190+
1. HTTP outgoing requests
191+
1. SQL drivers
105192

106-
* [Greeter](./example/http-database-greeter) - an instrumented HTTP server that queries a database
107-
* [Doubler](./example/kafka-producer-consumer) - an instrumented Kafka processor, that consumes and produces messages
108-
* [Event](./example/event) - Demonstrates usage of the Events API
109-
* [Autoprofile](./example/autoprofile) - Demonstrates usage of the AutoProfile™
110-
* [OpenTracing](./example/opentracing) - an example of usage of Instana tracer in an app instrumented with OpenTracing
111-
* [gRPC](./example/grpc-client-server) - an example of usage of Instana tracer in an app instrumented with gRPC
112-
* [Gin](./example/gin) - an example of usage of Instana tracer instrumenting a [`Gin`](github.com/gin-gonic/gin) application
113-
* [httprouter](./example/httprouter) - an example of usage of Instana tracer instrumenting a [`github.com/julienschmidt/httprouter`](https://github.com/julienschmidt/httprouter) router
193+
As we already covered HTTP incoming requests, we suggest that you understand how to collect data from HTTP outgoing requests and SQL driver databases.
114194

115-
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).
195+
Another interesting feature is the usage of additional packages located under [instrumentation](./instrumentation/). Each of these packages provide tracing for specific Go packages like the AWS SDK, Gorm and Fiber.
116196

117-
## Filing Issues
197+
## What's Next
118198

119-
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.
199+
1. [Tracer Options](docs/options.md)
200+
1. [Tracing HTTP Outgoing Requests](docs/roundtripper.md)
201+
1. [Tracing SQL Driver Databases](docs/sql.md)
202+
1. [Tracing Other Go Packages](docs/other_packages.md)
203+
1. [Instrumenting Code Manually](docs/manual_instrumentation.md)
120204

121205
<!-- Links section -->
122206

Diff for: ‎docs/manual_instrumentation.md

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
## Instrumenting Code Manually
2+
3+
The IBM Instana Go Tracer is built on top of the [Opentracing SDK](https://github.com/opentracing/opentracing-go).
4+
In practical terms this means that we provide concrete implementations for Opentracing's tracer, span interfaces and other required implementations to fulfill the SDK.
5+
6+
All these concrete implementations are publicly available and can be used by anyone.
7+
8+
The main difference between customers creating their own traces and using our SDK is that we encapsulate all the boilerplate code and data collection logic within the tracer and additional packages instrumentation for your convenience.
9+
10+
However, customers can extend it to create custom spans or provide extra tags with our SDK.
11+
12+
This section is dedicated to explore the creation of custom spans to be sent to the Instana Agent.
13+
14+
15+
### Understanding Entry Spans
16+
17+
A trace should always start with an entry span, which should be the parent span of subsequent spans.
18+
19+
If a span is created with the type `intermediate` or `exit` and it is sent to the Agent, the UI will provide a hollow entry span automatically called `Internal Trigger`.
20+
However, our tracer limits its own spans (which is, not custom spans) to always require an entry span.
21+
22+
A common use case is the instrumentation of outgoing HTTP requests with our SDK.
23+
These requests are `exit` spans, as they are "exiting" your application and require an entry span.
24+
Often this entry span will be an incoming HTTP request or a receiving queue message. But if this is not the case, an entry span must be manually created and attached as the parent span of the outgoing HTTP request (exit) span.
25+
26+
### Creating and Reporting Spans
27+
28+
You can create an entry span with the `StartSpan` method and by providing `ext.SpanKindRPCServer` as one of the options:
29+
30+
```go
31+
package main
32+
33+
import (
34+
instana "github.com/instana/go-sensor"
35+
ot "github.com/opentracing/opentracing-go"
36+
"github.com/opentracing/opentracing-go/ext"
37+
)
38+
39+
func main() {
40+
col := instana.InitCollector(&instana.Options{
41+
Service: "My Service",
42+
})
43+
44+
ps := col.StartSpan("my-entry-span", []ot.StartSpanOption{
45+
ext.SpanKindRPCServer,
46+
}...)
47+
48+
// Do some work
49+
50+
// Always make sure to call Finish to send the span to the Agent.
51+
ps.Finish()
52+
}
53+
```
54+
55+
The `StartSpan` method is compliant to the Opentracing interfaces, so you can rely on the Opentracing elements, such as `ot.StartSpanOption` for the span options or `ot.Tags` as part of the span options.
56+
You can also notice the usage of Opentracing's `ext.SpanKindRPCServer` to define the span as an entry span.
57+
58+
> [!NOTE]
59+
> You can use Opentracing's `ext.SpanKindRPCClient` to define an exit span. If no kind is provided, the span is assumed to be an `intermediate` span.
60+
61+
62+
### Correlating Spans
63+
64+
If you wish to define a relation for a span with respect to another span, so that multiple spans can be correlated to each other to form a more elaborate trace, you can use the method `ot.ChildOf()` as one of the options for child spans.
65+
66+
```go
67+
package main
68+
69+
import (
70+
instana "github.com/instana/go-sensor"
71+
ot "github.com/opentracing/opentracing-go"
72+
"github.com/opentracing/opentracing-go/ext"
73+
)
74+
75+
func main() {
76+
col := instana.InitCollector(&instana.Options{
77+
Service: "My Service",
78+
})
79+
80+
ps := col.StartSpan("my-parent-entry-span", []ot.StartSpanOption{
81+
ext.SpanKindRPCServer,
82+
}...)
83+
84+
// Do some work
85+
86+
ps.Finish()
87+
88+
exs := col.StartSpan("my-child-exit-span", []ot.StartSpanOption{
89+
ext.SpanKindRPCClient,
90+
91+
// Make sure to provide the parent span context to ot.ChildOf in order to correlate these spans
92+
ot.ChildOf(ps.Context()),
93+
}...)
94+
95+
// Do some work
96+
97+
exs.Finish()
98+
}
99+
```
100+
101+
-----
102+
[README](../README.md) |
103+
[Tracer Options](options.md) |
104+
[Tracing HTTP Outgoing Requests](roundtripper.md) |
105+
[Tracing SQL Driver Databases](sql.md) |
106+
[Tracing Other Go Packages](other_packages.md)

0 commit comments

Comments
 (0)