sdhook

README

About sdhook

Package sdhook provides a logrus compatible hook for Google Stackdriver logging.

Installation

Install in the usual Go way:

go get -u github.com/knq/sdhook

Usage

Simply create the hook, and add it to a logrus logger:

// create hook using service account credentials
h, err := sdhook.New(
	sdhook.GoogleServiceAccountCredentialsFile("./credentials.json"),
)

// create logger with extra fields
//
// logrus fields will be converted to Stackdriver labels
logger := logrus.New().WithFields(logrus.Fields{
	"field1": 15,
	"field2": 20,
})

// add hook
logger.Hooks.Add(h)

// log something
logger.Printf("something %d", 15)

The example above sends log entries directly to the logging API. If you have the logging agent running, you can send log entries to it instead, with the added benefit of having extra instance metadata added to your log entries by the agent. In the example above, the initialization would simply be:

// create hook using the logging agent
h, err := sdhook.New(
	sdhook.GoogleLoggingAgent(),
)

Please also see example/example.go for a more complete example.

Error Reporting

If you'd like to enable sending errors to Google's Error Reporting (https://cloud.google.com/error-reporting/), you have to set the name of the service, app or system you're running. Following the example above, the initialization would then be:

// create hook using the logging agent
h, err := sdhook.New(
	sdhook.GoogleLoggingAgent(),
	sdhook.ErrorReportingService("your-great-app"),
)

The value of the ErrorReportingService function parameter above corresponds to the string value you'd like to see in the service field of the Error Reporting payload, as defined by https://cloud.google.com/error-reporting/docs/formatting-error-messages

Also note that, if you enable error reporting, errors and messages of more severe levels go into the error log and will not be displayed in the regular log. The error log name is either defined by the ErrorReportingLogName function or defaults to <regular-log-name>_errors. This fulfills Google's Error Reporting requirement that the log name should have the string err in its name. See more in: https://cloud.google.com/error-reporting/docs/setup/ec2

To fulfill Google's Error Reporting requirement of a payload containing error stack frame information (file name, function name and line number), it assumes that this information has been added as a logrus.Field of name caller and type stack.Frame from Facebook's stack package. One way to easily achieve this transparently is to use another logrus Hook like Gurpartap's logrus-stack.

See GoDoc for a full API listing.

Documentation

Overview

Package sdhook provides a logrus compatible logging hook for Google Stackdriver logging.

Index

• Constants
• func HexToString(id string) string
• type Option
  • func EntriesService(service *logging.EntriesService) Option
  • func ErrorReportingLogName(name string) Option
  • func ErrorReportingService(service string) Option
  • func ErrorService(errorService *errorReporting.Service) Option
  • func GoogleComputeCredentials(serviceAccount string) Option
  • func GoogleLoggingAgent() Option
  • func GoogleServiceAccountCredentialsFile(path string) Option
  • func GoogleServiceAccountCredentialsJSON(buf []byte) Option
  • func HTTPClient(client *http.Client) Option
  • func Labels(labels map[string]string) Option
  • func Levels(levels ...logrus.Level) Option
  • func LimiterBurst(limiterBurst int) Option
  • func LimiterLimit(limiterLimit int) Option
  • func LogName(name string) Option
  • func LoggingService(service *logging.Service) Option
  • func MonitoredResource(resource *logging.MonitoredResource) Option
  • func PartialSuccess(enabled bool) Option
  • func ProjectID(projectID string) Option
  • func Resource(typ ResType, labels map[string]string) Option
• type ResType
• type StackdriverHook
  • func New(opts ...Option) (*StackdriverHook, error)
  • func (sh *StackdriverHook) Fire(entry *logrus.Entry) error
  • func (sh *StackdriverHook) Levels() []logrus.Level
  • func (sh *StackdriverHook) Wait()

Constants

const (
	// DefaultName is the default name passed to LogName when using service
	// account credentials.
	DefaultName = "default"
)

Functions

func HexToString

func HexToString(id string) string

Types

type Option

type Option func(*StackdriverHook) error

Option represents an option that modifies the Stackdriver hook settings.

func EntriesService

func EntriesService(service *logging.EntriesService) Option

EntriesService is an option that sets the Google API entry service to use with Stackdriver.

func ErrorReportingLogName

func ErrorReportingLogName(name string) Option

ErrorReportingLogName is an option that sets the log name to send with each error message for error reporting. Only used when ErrorReportingService has been set.

func ErrorReportingService

func ErrorReportingService(service string) Option

ErrorReportingService is an option that defines the name of the service being tracked for Stackdriver error reporting. See: https://cloud.google.com/error-reporting/docs/formatting-error-messages

func ErrorService

func ErrorService(errorService *errorReporting.Service) Option

ErrorService is an option that sets the Google API error reporting service to use.

func GoogleComputeCredentials

func GoogleComputeCredentials(serviceAccount string) Option

GoogleComputeCredentials is an option that loads the Google Service Account credentials from the GCE metadata associated with the GCE compute instance. If serviceAccount is empty, then the default service account credentials associated with the GCE instance will be used.

func GoogleLoggingAgent

func GoogleLoggingAgent() Option

func GoogleServiceAccountCredentialsFile

func GoogleServiceAccountCredentialsFile(path string) Option

GoogleServiceAccountCredentialsFile is an option that loads Google Service Account credentials for use with the StackdriverHook from the specified file.

Google Service Account credentials can be downloaded from the Google Cloud console: https://console.cloud.google.com/iam-admin/serviceaccounts/

func GoogleServiceAccountCredentialsJSON

func GoogleServiceAccountCredentialsJSON(buf []byte) Option

GoogleServiceAccountCredentialsJSON is an option that creates the Stackdriver logging service using the supplied Google service account credentials.

Google Service Account credentials can be downloaded from the Google Cloud console: https://console.cloud.google.com/iam-admin/serviceaccounts/

func HTTPClient

func HTTPClient(client *http.Client) Option

HTTPClient is an option that sets the http.Client to be used when creating the Stackdriver service.

func Labels

func Labels(labels map[string]string) Option

Labels is an option that sets the labels to send with each log entry.

func Levels

func Levels(levels ...logrus.Level) Option

Levels is an option that sets the logrus levels that the StackdriverHook will create log entries for.

func LimiterBurst

func LimiterBurst(limiterBurst int) Option

LimiterBurst is an option that sets x events at once

func LimiterLimit

func LimiterLimit(limiterLimit int) Option

LimiterLimit is an option that sets x events per second

func LogName

func LogName(name string) Option

LogName is an option that sets the log name to send with each log entry.

Log names are specified as "projects/{projectID}/logs/{logName}" if the projectID is set. Otherwise, it's just "{logName}"

func LoggingService

func LoggingService(service *logging.Service) Option

LoggingService is an option that sets the Google API logging service to use.

func MonitoredResource

func MonitoredResource(resource *logging.MonitoredResource) Option

MonitoredResource is an option that sets the monitored resource to send with each log entry.

func PartialSuccess

func PartialSuccess(enabled bool) Option

PartialSuccess is an option that toggles whether or not to write partial log entries.

func ProjectID

func ProjectID(projectID string) Option

ProjectID is an option that sets the project ID which is needed for the log name.

func Resource

func Resource(typ ResType, labels map[string]string) Option

Resource is an option that sets the resource information to send with each log entry.

Please see https://cloud.google.com/logging/docs/api/v2/resource-list for the list of labels required per ResType.

type ResType

type ResType string

ResType is a monitored resource descriptor type.

See https://cloud.google.com/logging/docs/api/v2/resource-list

const (
	ResTypeAPI                     ResType = "api"
	ResTypeAppScriptFunction       ResType = "app_script_function"
	ResTypeAwsEc2Instance          ResType = "aws_ec2_instance"
	ResTypeBigqueryResource        ResType = "bigquery_resource"
	ResTypeBuild                   ResType = "build"
	ResTypeClientAuthConfigBrand   ResType = "client_auth_config_brand"
	ResTypeClientAuthConfigClient  ResType = "client_auth_config_client"
	ResTypeCloudDebuggerResource   ResType = "cloud_debugger_resource"
	ResTypeCloudFunction           ResType = "cloud_function"
	ResTypeCloudRunRevision        ResType = "cloud_run_revision"
	ResTypeCloudsqlDatabase        ResType = "cloudsql_database"
	ResTypeContainer               ResType = "container"
	ResTypeDataflowStep            ResType = "dataflow_step"
	ResTypeDataprocCluster         ResType = "dataproc_cluster"
	ResTypeDeployment              ResType = "deployment"
	ResTypeDeploymentManagerType   ResType = "deployment_manager_type"
	ResTypeDNSManagedZone          ResType = "dns_managed_zone"
	ResTypeGaeApp                  ResType = "gae_app"
	ResTypeGceAutoscaler           ResType = "gce_autoscaler"
	ResTypeGceBackendService       ResType = "gce_backend_service"
	ResTypeGceDisk                 ResType = "gce_disk"
	ResTypeGceFirewallRule         ResType = "gce_firewall_rule"
	ResTypeGceForwardingRule       ResType = "gce_forwarding_rule"
	ResTypeGceHealthCheck          ResType = "gce_health_check"
	ResTypeGceImage                ResType = "gce_image"
	ResTypeGceInstance             ResType = "gce_instance"
	ResTypeGceInstanceGroup        ResType = "gce_instance_group"
	ResTypeGceInstanceGroupManager ResType = "gce_instance_group_manager"
	ResTypeGceInstanceTemplate     ResType = "gce_instance_template"
	ResTypeGceNetwork              ResType = "gce_network"
	ResTypeGceOperation            ResType = "gce_operation"
	ResTypeGceProject              ResType = "gce_project"
	ResTypeGceReservedAddress      ResType = "gce_reserved_address"
	ResTypeGceRoute                ResType = "gce_route"
	ResTypeGceRouter               ResType = "gce_router"
	ResTypeGceSnapshot             ResType = "gce_snapshot"
	ResTypeGceSslCertificate       ResType = "gce_ssl_certificate"
	ResTypeGceSubnetwork           ResType = "gce_subnetwork"
	ResTypeGceTargetHTTPProxy      ResType = "gce_target_http_proxy"
	ResTypeGceTargetHTTPSProxy     ResType = "gce_target_https_proxy"
	ResTypeGceTargetPool           ResType = "gce_target_pool"
	ResTypeGceURLMap               ResType = "gce_url_map"
	ResTypeGcsBucket               ResType = "gcs_bucket"
	ResTypeGkeCluster              ResType = "gke_cluster"
	ResTypeGlobal                  ResType = "global"
	ResTypeHTTPLoadBalancer        ResType = "http_load_balancer"
	ResTypeLoggingLog              ResType = "logging_log"
	ResTypeLoggingSink             ResType = "logging_sink"
	ResTypeMetric                  ResType = "metric"
	ResTypeMlJob                   ResType = "ml_job"
	ResTypeOrganization            ResType = "organization"
	ResTypeProject                 ResType = "project"
	ResTypeServiceAccount          ResType = "service_account"
	ResTypeTestserviceMatrix       ResType = "testservice_matrix"
	ResTypeVpnGateway              ResType = "vpn_gateway"
)

type StackdriverHook

type StackdriverHook struct {
	// contains filtered or unexported fields
}

StackdriverHook provides a logrus hook to Google Stackdriver logging.

func New

func New(opts ...Option) (*StackdriverHook, error)

New creates a StackdriverHook using the provided options that is suitible for using with logrus for logging to Google Stackdriver.

func (*StackdriverHook) Fire

func (sh *StackdriverHook) Fire(entry *logrus.Entry) error

Fire writes the message to the Stackdriver entry service.

func (*StackdriverHook) Levels

func (sh *StackdriverHook) Levels() []logrus.Level

Levels returns the logrus levels that this hook is applied to. This can be set using the Levels Option.

func (*StackdriverHook) Wait

func (sh *StackdriverHook) Wait()

Wait will return after all subroutines have returned. Use in conjunction with logrus return handling to ensure all of your logs are delivered before your program exits. `logrus.RegisterExitHandler(h.Wait)`