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/M2G/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.WithError(errors.WithStack(errors.New("error"))).Error("error")

Documentation

Overview

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

Index

• Constants
• func FormatStack(err error) (buffer []byte)
• type Option
  • func EntriesService(service *logging.EntriesService) Option
  • func ErrorClient(errorClient *errorreporting.Client) Option
  • func ErrorReportingLogName(name string) Option
  • func ErrorReportingService(service string) 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 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 FormatStack

func FormatStack(err error) (buffer []byte)

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 ErrorClient

func ErrorClient(errorClient *errorreporting.Client) Option

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

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 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 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"
	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)`