A native Go library to streamline and supercharge your interactions with the AWS CloudWatch Logs Insights service using minimalist, native Go, paradigms.

Incite makes it easier to write code to query your logs using AWS CloudWatch Logs Insights, and makes it possible to use Insights to query massive, arbitrary, amounts of log data reliably.

Features

• Streaming. AWS CloudWatch Logs Insights makes you poll your queries, requiring boilerplate code that is hard to write efficiently. Incite does the polling for you and lets you simply read your query results from a stream.
• Auto-Chunking. Every CloudWatch Logs Insights query is limited to 10,000 results. If your query exceeds 10K results, AWS advises you to break it into smaller time ranges. Incite does this chunking automatically and merges the results of all chunks into one convenient stream. Use the Chunk field in QuerySpec to enable chunking.
• Dynamic Splitting. Since v1.2.0, Incite can dynamically detect when a query chunk exceeds the 10K result limit, split that chunk into sub-chunks, and re-query the chunks, all automatically and without intervention. Use the SplitUntil field in QuerySpec to enable dynamic splitting.
• Multiplexing. Incite efficiently runs multiple queries at the same time and is smart enough to do this without getting throttled or going over your CloudWatch Logs service quota limits.
• Unmarshalling. The CloudWatch Logs Insights API can only give you unstructured key/value string pairs, requiring you to write boilerplate code to put your results into a useful structure for analysis. Incite lets you unmarshal your results into maps or structs using a single function call. Incite supports tag-based field mapping just like encoding/json. (And it supportsjson:"..." tags as well as its native incite:"..." tags, right out of the box!)
• Go Native. Incite gives you a more Go-friendly coding experience than the AWS SDK for Go, including getting rid of unnecessary pointers and using standard types like time.Time.

Getting Started

Get the code

1$ go get github.com/gogama/incite

Concepts

• For quick prototyping and scripting type work, simplify your life using the globalQuery function.
• When you need finer control over what your app is doing, create a new QueryManager using NewQueryManager and query it using its Query method.
• To read all the results from a stream, use the global ReadAll function.
• To unmarshal the results into a structure of your choice, use the global Unmarshal function.

A simple app

go
1package main
2
3import (
4	"context"
5	"fmt"
6	"time"
7
8	"github.com/aws/aws-sdk-go-v2/config"
9	"github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs"
10	"github.com/gogama/incite/v2"
11)
12
13func main() {
14	// Use the AWS SDK for Go V2 to get the CloudWatch API actions Incite needs.
15	// For simplicity, we assume that the correct AWS region and credentials are
16	// already set in the environment.
17
18	cfg, err := config.LoadDefaultConfig(context.TODO())
19	if err != nil {
20		return
21	}
22	a := cloudwatchlogs.NewFromConfig(cfg)
23
24	// Create a QueryManager. An alternative to using a QueryManager is just
25	// using the global scope Query function.
26	m := incite.NewQueryManager(incite.Config{Actions: a})
27	defer func() {
28		_ = m.Close()
29	}()
30
31	// Look at the last 15 minutes.
32	end := time.Now().Truncate(time.Millisecond)
33	start := end.Add(-15*time.Minute)
34
35	// Query the results.
36	s, err := m.Query(incite.QuerySpec{
37		Text:   "fields @timestamp, @message | filter @message =~ /foo/ | sort @timestamp desc",
38		Start:  start,
39		End:    end,
40		Groups: []string{"/my/log/group"},
41		Limit:  100,
42	})
43	if err != nil {
44		return
45	}
46	data, err := incite.ReadAll(s)
47	if err != nil {
48		return
49	}
50
51	// Unpack the results into a structured format.
52	var v []struct{
53		Timestamp time.Time `incite:"@timestamp"`
54		Message string      `incite:"@message"`
55	}
56	err = incite.Unmarshal(data, &v)
57	if err != nil {
58		return
59	}
60
61	// Print the results!
62	fmt.Println(v)
63}

Compatibility

Works with all Go versions 1.22 and up, and AWS SDK for Go V2 versions 1.36.5 and up.

Related

Official AWS documentation: Analyzing log data with CloudWatch Logs Insights. Find Insights' query syntax documentation here and the API reference here (look for StartQuery, GetQueryResults, and StopQuery).

License

This project is licensed under the terms of the MIT License.

Acknowledgements

Developer happiness on this project was embiggened by JetBrains, which generously donated an open source license for their lovely GoLand IDE. Thanks JetBrains!