README
¶
======================================
``timber`` -- Cedar Buildlogger Client
======================================
Overview
--------
The Timber library is used by Evergreen to send test results and
performance data to Cedar, and contains configuration utilities
for connecting to Cedar.
See `cedar <https://github.com/evergreen-ci/cedar>`_ and
`poplar <https://github.com/evergreen-ci/poplar>`_ for more information.
It also implements a grip Sender backed by Cedar Buildlogger which is
still used for some log storage purposes by Evergreen.
See `grip <https://github.com/mongodb/grip>`_ for more information.
Features
--------
When initializing a Sender with timber, a gRPC connection to a Cedar backed
application is established. Log lines are buffered and sent over in batches to
Cedar via this gRPC connection. Buffer size, flush intervals, etc. are all
configurable. The Sender is thread-safe.
Code Example
------------
Using the timber Sender is straightforward, once the logger is setup it can be
passed around anywhere in your code. Log lines are sent using the Send
command: ::
opts := &timber.LoggerOptions{}
// populate options struct
// ...
l := timber.MakeLogger(ctx, "logging-example", opts)
grip.SetSender(l)
l.Send(message.ConvertToComposer(level.Info, "logging is easy!"))
l.Send(message.ConvertToComposer(level.Debug, "another example"))
// make sure to close our your logger!
err := l.Close()
Development
-----------
The timber project uses a ``makefile`` to coordinate testing.
The makefile provides the following targets:
``build``
Compiles non-test code.
``test``
Runs all tests, sequentially, for all packages.
``test-<package>``
Runs all tests for a specific package.
``race``, ``race-<package>``
As with their ``test`` counterpart, these targets run tests with
the race detector enabled.
``lint``, ``lint-<package>``
Installs and runs the ``gometaliter`` with appropriate settings to
lint the project.
File tickets in Jira with the `MAKE <https://jira.mongodb.org/browse/MAKE>`_
project.
Documentation
-------------
See the `timber godoc <https://godoc.org/github.com/evergreen-ci/timber>`_
for complete documentation.
See the `grip godoc <https://godoc.org/github.com/mongodb/grip/send#Sender>`_
for documentation of the Sender interface.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DialCedar ¶
func DialCedar(ctx context.Context, client *http.Client, opts DialCedarOptions) (*grpc.ClientConn, error)
DialCedar is a convenience function for creating a RPC client connection with cedar via gRPC. This wraps the same function in aviation.
func NewPaginatedReadCloser ¶
func NewPaginatedReadCloser(ctx context.Context, resp *http.Response, opts GetOptions) *paginatedReadCloser
NewPaginatedReadCloser returns an io.ReadCloser implementation for paginated HTTP responses from a Cedar service. It is safe to pass in a non-paginated response, thus the caller need not check for the appropriate header keys. GetOptions is used to make any subsequent page requests.
Types ¶
type ConnectionOptions ¶
type ConnectionOptions struct {
DialOpts DialCedarOptions
Client http.Client
}
ConnectionOptions contains the options needed to create a gRPC connection with cedar.
func (ConnectionOptions) Validate ¶
func (opts ConnectionOptions) Validate() error
type DialCedarOptions ¶
type DialCedarOptions services.DialCedarOptions
DialCedarOptions describes the options for the DialCedar function. The base address defaults to `cedar.mongodb.com` and the RPC port to 7070. If a base address is provided the RPC port must also be provided. Username and either password or API key must always be provided. This aliases the same type in aviation.
type GetOptions ¶
type GetOptions struct {
// The Cedar service's base HTTP URL for the request.
BaseURL string
// The user cookie for Cedar authorization. Optional.
Cookie *http.Cookie
// User API key and name for request header.
UserKey string
UserName string
// HTTP client for connecting to the Cedar service. Optional.
HTTPClient *http.Client
}
GetOptions specify the required and optional information to create an HTTP GET request to Cedar.
func (GetOptions) DoReq ¶
func (opts GetOptions) DoReq(ctx context.Context, url string, body io.Reader) (*http.Response, error)
DoReq makes an HTTP request to the Cedar service.
func (GetOptions) Validate ¶
func (opts GetOptions) Validate() error
Validate ensures GetOptions is configured correctly.
Source Files
Directories