diff --git a/README.md b/README.md index 0ed62e9..fa8b7c8 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,141 @@ # wavefront-sdk-go [![build status][ci-img]][ci] [![Go Report Card][go-report-img]][go-report] [![GoDoc][godoc-img]][godoc] -This library provides support for sending metrics, histograms and tracing spans to Wavefront via proxy or direct ingestion using the `Sender` interface. - -## Requirements -- Go 1.9 or higher - -## Usage - -Import the `senders` package and create a proxy or direct sender as given below. - -```go -import ( - wavefront "github.com/wavefronthq/wavefront-sdk-go/senders" -) -``` - -### Proxy Sender -Depending on the data you wish to send to Wavefront (metrics, distributions and/or spans), enable the relevant ports on the proxy and initialize the proxy sender as follows: +## Table of Content +* [Prerequisites](#Prerequisites) +* [Set Up a Sender](#set-up-a-sender) +* [Send Data to Wavefront](#send-data-to-wavefront) +* [Close the Sender](#close-the-sender) +* [License](#License) +* [How to Get Support and Contribute](#how-to-get-support-and-contribute) + +# Welcome to the Wavefront Go SDK + +Wavefront by VMware Go SDK lets you send raw data from your Go application to Wavefront using a `Sender` interface. The data is then stored as metrics, histograms, and trace data. This SDK is also called the Wavefront Sender SDK for Go. + +Although this library is mostly used by the other Wavefront Go SDKs to send data to Wavefront, you can also use this SDK directly. For example, you can send data directly from a data store or CSV file to Wavefront. + +**Before you start implementing, let us make sure you are using the correct SDK!** + +![Go Sender SDK Decision Tree](docs/go_sender_sdk.png) + +> ***Note***: +>
+> * **This is the Wavefront by VMware SDK for Go (Wavefront Sender SDK for Go)!** +> If this SDK is not what you were looking for, see the [table](#wavefront-sdks) below. + +#### Wavefront SDKs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SDK TypeSDK DescriptionSupported Languages
OpenTracing SDKImplements the OpenTracing specification. Lets you define, collect, and report custom trace data from any part of your application code.
Automatically derives Rate Errors Duration (RED) metrics from the reported spans. 		+ +
Metrics SDKImplements a standard metrics library. Lets you define, collect, and report custom business metrics and histograms from any part of your application code. + +
Framework SDKReports predefined traces, metrics, and histograms from the APIs of a supported app framework. Lets you get started quickly with minimal code changes. + +
Sender SDKLets you send raw data to Wavefront for storage as metrics, histograms, or traces, e.g., to import CSV data into Wavefront. + + +
+ +## Prerequisites +* Go 1.9 or higher. +* Import the `senders` package. + ```go + import ( + wavefront "github.com/wavefronthq/wavefront-sdk-go/senders" + ) + ``` + +## Set Up a Sender + +You can send metrics, histograms, or trace data from your application to the Wavefront service using a Wavefront proxy or direct ingestions. + +* Option 1: Use a [**Wavefront proxy**](https://docs.wavefront.com/proxies.html), which then forwards the data to the Wavefront service. This is the recommended choice for a large-scale deployment that needs resilience to internet outages, control over data queuing and filtering, and more. +[Create a ProxyConfiguration](#option-1-sending-data-via-the-wavefront-proxy) to send data to a Wavefront proxy. + +* Use [**direct ingestion**](https://docs.wavefront.com/direct_ingestion.html) to send the data directly to the Wavefront service. This is the simplest way to get up and running quickly. +[Create a DirectConfiguration](#option-2-sending-data-via-direct-ingestion) to send data directly to a Wavefront service. + +### Option 1: Sending Data via the Wavefront Proxy +Depending on the data you wish to send to Wavefront (metrics, distributions (histograms) and/or spans), enable the relevant ports on the proxy and initialize the proxy sender as follows: ```go import ( @@ -47,7 +166,7 @@ func main() { } ``` -### Direct Sender +### Option 2: Sending Data via Direct Ingestion ```go import ( @@ -90,9 +209,12 @@ func main() { ``` -### Sending data to Wavefront +## Send Data to Wavefront -Use the `Sender` interface for sending data to Wavefront. +Wavefront supports different metric types, such as gauges, counters, delta counters, histograms, traces, and spans. See [Metrics](https://docs.wavefront.com/metric_types.html) for details. To send data to Wavefront using `Sender` you need to instantiate the following: + * [Metrics and Delta Counters](#Metrics-and-Delta-Counters) + * [Distributions (Histograms)](#distributions-histograms) + * [Tracing Spans](#Tracing-Spans) #### Metrics and Delta Counters @@ -108,7 +230,9 @@ sender.SendMetric("new-york.power.usage", 42422.0, 0, "go_test", map[string]stri sender.SendDeltaCounter("lambda.thumbnail.generate", 10.0, "thumbnail_service", map[string]string{"format" : "jpeg"}) ``` -#### Distributions +***Note***: If your `metricName` has a bad character, that character is replaced with a `-`. + +#### Distributions (Histograms) ```go import "github.com/wavefronthq/wavefront-sdk-go/histogram" @@ -161,13 +285,13 @@ sender.SendSpan("getAllUsers", 1552949776000, 343, "localhost", }, nil) ``` -**Note:** The tracing and span SDK APIs are designed to serve as low-level endpoints. For most use cases, we recommend using -opentracing with the ```WavefrontTracer```. - -For more information on OpenTracing, please refer the OpenTracing project: https://github.com/opentracing/opentracing-go. To use OpenTracing with Wavefront, please refer to https://github.com/wavefrontHQ/wavefront-opentracing-sdk-go. +***Note:*** The tracing and span SDK APIs are designed to serve as low-level endpoints. For most use cases, we recommend using +the OpenTracing SDK with the `WavefrontTracer`. +* See the [Go OpenTracing project](https://github.com/opentracing/opentracing-go) for details. +* To use OpenTracing with Wavefront, see the [Wavefront Go OpenTracing SDK](https://github.com/wavefrontHQ/wavefront-opentracing-sdk-go). -#### Closing the Sender -It is recommended to flush and close the sender before shutting down your application. +## Close the Sender +Before shutting down your application, flush the buffer and close the sender. ```go // failures observed while sending metrics/histograms/spans, can be obtained as follows: @@ -180,6 +304,14 @@ sender.Flush() sender.Close() ``` +## License +[Apache 2.0 License](LICENSE). + +## How to Get Support and Contribute + +* Reach out to us on our public [Slack channel](https://www.wavefront.com/join-public-slack). +* If you run into any issues, let us know by creating a GitHub issue. + [ci-img]: https://travis-ci.com/wavefrontHQ/wavefront-sdk-go.svg?branch=master [ci]: https://travis-ci.com/wavefrontHQ/wavefront-sdk-go [godoc]: https://godoc.org/github.com/wavefrontHQ/wavefront-sdk-go/senders diff --git a/docs/apptags.md b/docs/apptags.md deleted file mode 100644 index 2dd7e16..0000000 --- a/docs/apptags.md +++ /dev/null @@ -1,30 +0,0 @@ -# Application Tags - -Many Wavefront SDKs require you to specify _application tags_ that describe the architecture of your application as it is deployed. These tags are associated with the metrics and trace data sent from the instrumented microservices in your application. You specify a separate set of application tags for each microservice you instrument. Wavefront uses these tags to aggregate and filter data at different levels of granularity. - -**Required tags** enable you to drill down into the data for a particular service: -* `application` - Name that identifies your Java application, for example: `OrderingApp`. All microservices in the same application should share the same application name. -* `service` - Name that identifies the microservice within your application, for example: `inventory`. Each microservice should have its own service name. - -**Optional tags** enable you to use the physical topology of your application to further filter your data: -* `cluster` - Name of a group of related hosts that serves as a cluster or region in which the application will run, for example: `us-west-2`. -* `shard` - Name of a subgroup of hosts within a cluster that serve as a partition, replica, shard, or mirror, for example: `secondary`. - -You can also optionally add custom tags specific to your application. - -Application tags and their values are encapsulated in a `Tags` object in your microservice’s code. Because the tags describe the application’s architecture as it is deployed, your code typically obtains values for the tags from a YAML configuration file, either provided by the SDK or through a custom mechanism implemented by your application. - -To create a `Tags` instance with values for the required `application` and `service` tags: -```go -import ( - "github.com/wavefronthq/wavefront-sdk-go/application" -) - -appTags := application.New("OrderingApp", "inventory") -``` - -To set the optional `cluster` and `shard` tags: -``` -appTags.Cluster = "us-west-2" -appTags.Shard = "primary" -``` diff --git a/docs/go_sender_sdk.png b/docs/go_sender_sdk.png new file mode 100644 index 0000000..1a5d248 Binary files /dev/null and b/docs/go_sender_sdk.png differ diff --git a/docs/sender.md b/docs/sender.md deleted file mode 100644 index edd90be..0000000 --- a/docs/sender.md +++ /dev/null @@ -1,143 +0,0 @@ -# Set Up a Wavefront Sender - -You can choose to send metrics, histograms, or trace data from your application to the Wavefront service using one of the following techniques: -* Use [direct ingestion](https://docs.wavefront.com/direct_ingestion.html) to send the data directly to the Wavefront service. This is the simplest way to get up and running quickly. -* Use a [Wavefront proxy](https://docs.wavefront.com/proxies.html), which then forwards the data to the Wavefront service. This is the recommended choice for a large-scale deployment that needs resilience to internet outages, control over data queuing and filtering, and more. - -To implement this choice: - -1. Import the `senders` package: - - ``` - import ( - "github.com/wavefronthq/wavefront-sdk-go/senders" - ) - ``` -2. Create a `Sender` instance: - * Option 1: [Create a direct `Sender`](#option-1-create-a-direct-sender) to send data directly to a Wavefront service. - * Option 2: [Create a proxy `Sender`](#option-2-create-a-proxy-sender) to send data to a Wavefront proxy. - -## Option 1: Create a Direct Sender -To create a direct `Sender`, you configure it to send data directly to Wavefront. - -### Step 1. Obtain Wavefront Access Information -Gather the following access information: - -* Identify the URL of your Wavefront instance. This is the URL you connect to when you log in to Wavefront, typically something like `https://.wavefront.com`. -* In Wavefront, verify that you have Direct Data Ingestion permission, and [obtain an API token](http://docs.wavefront.com/wavefront_api.html#generating-an-api-token). - -### Step 2. Configure the Direct Sender -Create a `DirectConfiguration` that has the server and token information you obtained in Step 1. - -You can optionally tune the following ingestion properties: - -* Max buffer size - Internal buffer capacity of the direct `Sender`, which helps with handling brief increases in data and buffering on errors. Any data in excess of this size is dropped. Separate buffers are maintained per data type (metrics, spans and distributions). -* Flush interval - Interval for flushing data from the direct `Sender` directly to Wavefront. -* Batch size - Amount of data to send to Wavefront in each flush interval. - -Together, the flush interval and batch size control the maximum theoretical throughput of the direct `Sender`. - -Default values should suffice for most use cases. -You should override the defaults _only_ to set higher values. - -```go -import ( - time - "github.com/wavefronthq/wavefront-sdk-go/senders" -) - -func main() { - directCfg := &senders.DirectConfiguration { - // Your Wavefront instance URL - Server : "https://INSTANCE.wavefront.com", - - // Wavefront API token created with direct ingestion permission - Token : "YOUR_API_TOKEN", - - // Optional: Override the batch size (in data points). Default: 10,000. Recommended not to exceed 40,000. - BatchSize : 20000, - - // Optional: Override the max buffer size (in data points). Default: 50,000. Higher values could use more memory. - MaxBufferSize : 50000, - - // Optional: Override the flush interval (in seconds). Default: 1 second - FlushIntervalSeconds : 2, - } - - // Create the direct sender - sender, err := senders.NewDirectSender(directCfg) - if err != nil { - // handle error - } - ... // Use the direct sender to send data -} -``` - - -## Option 2: Create a Proxy Sender - -**Note:** Before your application can use a proxy `Sender`, you must [set up and start a Wavefront proxy](https://github.com/wavefrontHQ/java/tree/master/proxy#set-up-a-wavefront-proxy). - -To create a proxy `Sender`, you configure it with a `ProxyConfiguration` that includes: - -* The name of the host that will run the Wavefront proxy. -* One or more proxy listening ports to send data to. The ports you specify depend on the kinds of data you want to send (metrics, histograms, and/or trace data). You must specify at least one listener port. -* Optional setting for tuning communication with the proxy. - -```go -import ( - "github.com/wavefronthq/wavefront-sdk-go/senders" -) - -func main() { - proxyCfg := &senders.ProxyConfiguration { - // The proxy hostname or address - Host : "proxyHostname or proxyIPAddress", - - // Set at least one port: - - // Set the proxy port to send metrics to. Default: 2878 - MetricsPort : 2878, - - // Set a proxy port to send histograms to. Recommended: 2878 - DistributionPort: 2878, - - // Set a proxy port to send trace data to. Recommended: 30000 - TracingPort : 30000, - - // Optional: Set a nondefault interval (in seconds) for flushing data from the sender to the proxy. Default: 5 seconds - FlushIntervalSeconds: 10 - - } - - // Create the proxy sender - sender, err := senders.NewProxySender(proxyCfg) - if err != nil { - // handle error - } - - ... // Use the proxy sender to send data -} -``` - -**Note:** When you [set up a Wavefront proxy](https://github.com/wavefrontHQ/java/tree/master/proxy#set-up-a-wavefront-proxy) on the specified proxy host, you specify the port it will listen to for each type of data to be sent. The proxy `Sender` must send data to the same ports that the Wavefront proxy listens to. Consequently, the port-related `Sender` configuration fields must specify the same port numbers as the corresponding proxy configuration properties: - -| `ProxyConfiguration` field | Corresponding property in `wavefront.conf` | -| ----- | -------- | -| `MetricsPort` | `pushListenerPorts=` | -| `DistributionPort` | `histogramDistListenerPorts=` | -| `TracingPort` | `traceListenerPorts=` | - -# Share a Wavefront Sender - -Various Wavefront SDKs for Go use this library and require a `Sender` instance. - -If you are using multiple Wavefront Go SDKs within the same process, you can create a single `Sender` and share it among the SDKs. - - -**Note:** If you use SDKs in different processes, you must create one `Sender` instance per process.