Documentation
¶
Index ¶
- Constants
- Variables
- func ConvertArgs(args ...interface{}) map[string]interface{}
- func InitSysEventer(log hclog.Logger, serializationLock *sync.Mutex, serverName string, ...) error
- func NewEventerContext(ctx context.Context, eventer *Eventer) (context.Context, error)
- func NewId(prefix string) (string, error)
- func NewRequestInfoContext(ctx context.Context, info *RequestInfo) (context.Context, error)
- func TestEnableEventing(t *testing.T, enable bool)
- func TestResetSystEventer(t *testing.T)
- func WriteAudit(ctx context.Context, caller Op, opt ...Option) error
- func WriteError(ctx context.Context, caller Op, e error, opt ...Option)
- func WriteObservation(ctx context.Context, caller Op, opt ...Option) error
- func WriteSysEvent(ctx context.Context, caller Op, msg string, args ...interface{})
- type Auth
- type DeliveryGuarantee
- type Eventer
- type EventerConfig
- type FileSinkTypeConfig
- type FilterType
- type GrantsInfo
- type GrantsPair
- type Id
- type Op
- type Option
- func TestWithAuditSink(t *testing.T) Option
- func TestWithBroker(t *testing.T, b broker) Option
- func TestWithObservationSink(t *testing.T) Option
- func WithAllow(f ...string) Option
- func WithAuth(a *Auth) Option
- func WithDeny(f ...string) Option
- func WithDetails(args ...interface{}) Option
- func WithEventer(e *Eventer) Option
- func WithEventerConfig(c *EventerConfig) Option
- func WithFlush() Option
- func WithHeader(args ...interface{}) Option
- func WithId(id string) Option
- func WithInfo(args ...interface{}) Option
- func WithInfoMsg(msg string, args ...interface{}) Option
- func WithNow(now time.Time) Option
- func WithRequest(r *Request) Option
- func WithRequestInfo(i *RequestInfo) Option
- func WithResponse(r *Response) Option
- func WithSchema(url *url.URL) Option
- type Request
- type RequestInfo
- type Response
- type SinkConfig
- type SinkFilter
- type SinkFormat
- type SinkType
- type StderrSinkTypeConfig
- type TestConfig
- type Type
- type UserInfo
Constants ¶
const ( ServerName string = "server_name" // ServerName: event source server name ServerAddress string = "server_addr" // ServerAddress: event source server address )
Define a set of common keys and values to use in event payload maps. Having and using a common set will allow operators to more easily define event filters.
const ( OpField = "op" // OpField in an event. RequestInfoField = "request_info" // RequestInfoField in an event. VersionField = "version" // VersionField in an event DetailsField = "details" // Details field in an event. HeaderField = "header" // HeaderField in an event. IdField = "id" // IdField in an event. CreatedAtField = "created_at" // CreatedAtField in an event. TypeField = "type" // TypeField in an event. )
const (
ApiRequest auditEventType = "APIRequest" // ApiRequest defines an API request audit event type
)
const IdPrefix = "e"
const MissingKey = "EXTRA_VALUE_AT_END"
MissingKey defines a key to be used as the "missing key" when ConvertArgs has an odd number of args (it's missing a key in its key/value pairs)
Variables ¶
Functions ¶
func ConvertArgs ¶ added in v0.5.0
func ConvertArgs(args ...interface{}) map[string]interface{}
ConvertArgs will convert the key/value pair args to a map. If the args provided are an odd number (they're missing a key in their key/value pairs) then MissingKey is used to the missing key.
func InitSysEventer ¶
func InitSysEventer(log hclog.Logger, serializationLock *sync.Mutex, serverName string, opt ...Option) error
InitSysEventer provides a mechanism to initialize a "system wide" eventer singleton for Boundary. Support the options of: WithEventer(...) and WithEventerConfig(...)
IMPORTANT: Eventers cannot share file sinks, which likely means that each process should only have one Eventer. In practice this means the process Server (Controller or Worker) and the SysEventer both need a pointer to a single Eventer.
func NewEventerContext ¶
NewEventerContext will return a context containing a value of the provided Eventer
func NewId ¶ added in v0.5.0
NewId is a bit of a modified NewId has been done to stop a circular dependency with the errors package that is caused by importing boundary/internal/db
func NewRequestInfoContext ¶
NewRequestInfoContext will return a context containing a value for the provided RequestInfo
func TestEnableEventing ¶ added in v0.5.0
TestEnableEventing will enable eventing via it's envvar globals.BOUNDARY_DEVELOPER_ENABLE_EVENTS
func TestResetSystEventer ¶
TestResetSysEventer will reset event.syseventer to an uninitialized state.
func WriteAudit ¶
WriteAudit will write an audit event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an error is returned.
At least one and any combination of the supported options may be used: WithRequest, WithResponse, WithAuth, WithId, WithFlush and WithRequestInfo. All other options are ignored.
func WriteError ¶
WriteError will write an error event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an hclog.Logger will be created and used.
The options WithInfoMsg, WithInfo, WithId and WithRequestInfo are supported and all other options are ignored.
func WriteObservation ¶
WriteObservation will write an observation event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an error is returned.
At least one and any combination of the supported options may be used: WithHeader, WithDetails, WithId, WithFlush and WithRequestInfo. All other options are ignored.
func WriteSysEvent ¶ added in v0.4.0
WriteSysEvent will write a sysevent using the eventer from event.SysEventer() if no eventer can be found an hclog.Logger will be created and used. The args are and optional set of key/value pairs about the event.
This function should never be used when sending events while handling API requests.
Types ¶
type Auth ¶
type Auth struct { // AccessorId is a std audit field == auth_token public_id AccessorId string `json:"accessor_id"` UserInfo *UserInfo `json:"user_info,omitempty"` // boundary field GrantsInfo *GrantsInfo `json:"grants_info,omitempty"` UserEmail string `json:"email,omitempty"` UserName string `json:"name,omitempty"` }
type DeliveryGuarantee ¶
type DeliveryGuarantee string // DeliveryGuarantee defines the guarantees around delivery of an event type within config
const ( DefaultDeliveryGuarantee DeliveryGuarantee = "" // DefaultDeliveryGuarantee will be BestEffort Enforced DeliveryGuarantee = "enforced" // Enforced means that a delivery guarantee is enforced BestEffort DeliveryGuarantee = "best-effort" // BestEffort means that a best effort will be made to deliver an event )
type Eventer ¶
type Eventer struct {
// contains filtered or unexported fields
}
Eventer provides a method to send events to pipelines of sinks
func EventerFromContext ¶
EventerFromContext attempts to get the eventer value from the context provided
func NewEventer ¶
func NewEventer(log hclog.Logger, serializationLock *sync.Mutex, serverName string, c EventerConfig, opt ...Option) (*Eventer, error)
NewEventer creates a new Eventer using the config. Supports options: WithNow, WithSerializationLock, WithBroker
func SysEventer ¶
func SysEventer() *Eventer
SysEventer returns the "system wide" eventer for Boundary and can/will return a nil Eventer
func (*Eventer) FlushNodes ¶
FlushNodes will flush any of the eventer's flushable nodes. This needs to be called whenever Boundary is stopping (aka shutting down).
func (*Eventer) Reopen ¶
Reopen can used during a SIGHUP to reopen nodes, most importantly the underlying file sinks.
func (*Eventer) StandardLogger ¶ added in v0.5.0
func (e *Eventer) StandardLogger(ctx context.Context, loggerName string, typ Type) (*log.Logger, error)
StandardLogger will create *log.Logger that will emit events through this Logger. This allows packages that require the stdlib log to emit events instead.
type EventerConfig ¶
type EventerConfig struct { AuditEnabled bool `hcl:"audit_enabled"` // AuditEnabled specifies if audit events should be emitted. ObservationsEnabled bool `hcl:"observations_enabled"` // ObservationsEnabled specifies if observation events should be emitted. SysEventsEnabled bool `hcl:"sysevents_enabled"` // SysEventsEnabled specifies if sysevents should be emitted. Sinks []SinkConfig `hcl:"-"` // Sinks are all the configured sinks }
EventerConfig supplies all the configuration needed to create/config an Eventer.
func DefaultEventerConfig ¶ added in v0.5.0
func DefaultEventerConfig() *EventerConfig
func TestGetEventerConfig ¶ added in v0.5.0
func TestGetEventerConfig(t *testing.T, e *Eventer) EventerConfig
TestGetEventerConfig is a test accessor for the eventer's config
func (*EventerConfig) Validate ¶ added in v0.5.0
func (c *EventerConfig) Validate() error
Validate will Validate the config. A config isn't required to have any sinks to be valid.
type FileSinkTypeConfig ¶ added in v0.5.0
type FileSinkTypeConfig struct { Path string `hcl:"path" mapstructure:"path"` // Path defines the file path for the sink FileName string `hcl:"file_name" mapstructure:"file_name"` // FileName defines the file name for the sink RotateBytes int `hcl:"rotate_bytes" mapstructure:"rotate_bytes"` // RotateBytes defines the number of bytes that should trigger rotation of a FileSink RotateDuration time.Duration `mapstructure:"rotate_duration"` // RotateDuration defines how often a FileSink should be rotated RotateDurationHCL string `hcl:"rotate_duration" json:"-"` // RotateDurationHCL defines hcl string version of RotateDuration RotateMaxFiles int `hcl:"rotate_max_files" mapstructure:"rotate_max_files"` // RotateMaxFiles defines how may historical rotated files should be kept for a FileSink }
FileSinkTypeConfig contains configuration structures for file sink types
type FilterType ¶ added in v0.5.0
type FilterType string
FilterType defines a type for filters (allow or deny)
const ( AllowFilter FilterType = "allow" // AllowFilter defines a filter type for "allow" DenyFilter FilterType = "deny" // DenyFilter defines a filter type for "deny" )
type GrantsInfo ¶
type GrantsInfo struct {
Grants []GrantsPair `json:"grants_pair,omitempty"`
}
type GrantsPair ¶
type Option ¶
type Option func(*options)
Option - how Options are passed as arguments.
func TestWithAuditSink ¶ added in v0.5.0
TestWithAuditSink is an unexported and a test option
func TestWithBroker ¶ added in v0.5.0
TestWithBroker is an unexported and a test option for passing in an optional broker
func TestWithObservationSink ¶ added in v0.5.0
TestWithObservationSink is an unexported and a test option
func WithDetails ¶
func WithDetails(args ...interface{}) Option
WithDetails allows an optional set of key/value pairs about an observation event at the detail level and observation events may have multiple "details"
func WithEventer ¶ added in v0.5.0
WithEventer allows an optional eventer
func WithEventerConfig ¶ added in v0.5.0
func WithEventerConfig(c *EventerConfig) Option
WithEventer allows an optional eventer config
func WithHeader ¶
func WithHeader(args ...interface{}) Option
WithHeader allows an optional set of key/value pairs about an event at the header level and observation events will only have one "header"
func WithInfo ¶ added in v0.5.0
func WithInfo(args ...interface{}) Option
WithInfo allows an optional info key/value pairs about an error event. If used in conjunction with the WithInfoMsg(...) option, and WithInfoMsg(...) is specified after WithInfo(...), then WithInfoMsg(...) will overwrite any values from WithInfo(...). It's recommend that these two options not be used together.
func WithInfoMsg ¶ added in v0.5.0
WithInfoMsg allows an optional msg and optional info key/value pairs about an error event. If used in conjunction with the WithInfo(...) option, and WithInfo(...) is specified after WithInfoMsg(...), then WithInfo(...) will overwrite any values from WithInfo(...). It's recommend that these two options not be used together.
func WithRequestInfo ¶
func WithRequestInfo(i *RequestInfo) Option
WithRequestInfo allows an optional RequestInfo
func WithSchema ¶ added in v0.5.0
WithSchema is an optional schema for the cloudevents
type RequestInfo ¶
type RequestInfo struct { EventId string `json:"-"` Id string `json:"id,omitempty"` Method string `json:"method,omitempty"` Path string `json:"path,omitempty"` PublicId string `json:"public_id,omitempty"` }
RequestInfo defines the fields captured about a Boundary request.
func RequestInfoFromContext ¶
func RequestInfoFromContext(ctx context.Context) (*RequestInfo, bool)
RequestInfoFromContext attempts to get the RequestInfo value from the context provided
func TestRequestInfo ¶
func TestRequestInfo(t *testing.T) *RequestInfo
TestRequestInfo provides a test RequestInfo
type SinkConfig ¶
type SinkConfig struct { Name string `hcl:"name"` // Name defines a name for the sink. Description string `hcl:"description"` // Description defines a description for the sink. EventTypes []Type `hcl:"event_types"` // EventTypes defines a list of event types that will be sent to the sink. See the docs for EventTypes for a list of accepted values. EventSourceUrl string `hcl:"event_source_url"` // EventSource defines an optional event source URL for the sink. If not defined a default source will be composed of the https://hashicorp.com/boundary.io/ServerName/Path/FileName. AllowFilters []string `hcl:"allow_filters"` // AllowFilters define a set predicates for including an event in the sink. If any filter matches, the event will be included. The filter should be in a format supported by hashicorp/go-bexpr. DenyFilters []string `hcl:"deny_filters"` // DenyFilters define a set predicates for excluding an event in the sink. If any filter matches, the event will be excluded. The filter should be in a format supported by hashicorp/go-bexpr. Format SinkFormat `hcl:"format"` // Format defines the format for the sink (JSONSinkFormat or TextSinkFormat). Type SinkType `hcl:"type"` // Type defines the type of sink (StderrSink or FileSink). StderrConfig *StderrSinkTypeConfig `hcl:"stderr"` // StderrConfig defines parameters for a stderr output. FileConfig *FileSinkTypeConfig `hcl:"file"` // FileConfig defines parameters for a file output. }
SinkConfig defines the configuration for a Eventer sink
func DefaultSink ¶ added in v0.5.0
func DefaultSink() SinkConfig
func (*SinkConfig) Validate ¶ added in v0.5.0
func (sc *SinkConfig) Validate() error
type SinkFilter ¶ added in v0.5.0
type SinkFilter struct { Type FilterType `hcl:"type"` // Type of filter (allow or deny) Filter string `hcl:"filter"` // Filter in a format supported by hashicorp/go-bexpr. }
SinkFilter defines an event filter (allow or deny) for a sink
func (SinkFilter) Validate ¶ added in v0.5.0
func (s SinkFilter) Validate() error
Validate a SinkFilter
type SinkFormat ¶
type SinkFormat string // SinkFormat defines the formatting for a sink in a config file stanza (json)
const ( JSONSinkFormat SinkFormat = "cloudevents-json" // JSONSinkFormat means the event is formatted as JSON TextSinkFormat SinkFormat = "cloudevents-text" // TextSinkFormat means the event is formmatted as text TextHclogSinkFormat SinkFormat = "hclog-text" // TextHclogSinkFormat means the event is formatted as an hclog text entry JSONHclogSinkFormat SinkFormat = "hclog-json" // JSONHclogSinkFormat means the event is formated as an hclog json entry )
func (SinkFormat) Validate ¶ added in v0.5.0
func (f SinkFormat) Validate() error
type SinkType ¶
type SinkType string // SinkType defines the type of sink in a config stanza (file, stderr)
type StderrSinkTypeConfig ¶ added in v0.5.0
type StderrSinkTypeConfig struct{}
StderrSinkTypeConfig contains configuration structures for file sink types
type TestConfig ¶
type TestConfig struct { EventerConfig EventerConfig AllEvents *os.File ErrorEvents *os.File ObservationEvents *os.File AuditEvents *os.File }
func TestEventerConfig ¶
func TestEventerConfig(t *testing.T, testName string, opt ...Option) TestConfig
TestEventerConfig creates a test config and registers a cleanup func for its test tmp files.
type Type ¶
type Type string
Type represents the event's type
const ( EveryType Type = "*" // EveryType represents every (all) types of events ObservationType Type = "observation" // ObservationType represents observation events AuditType Type = "audit" // AuditType represents audit events ErrorType Type = "error" // ErrorType represents error events SystemType Type = "system" // SysType represents system events )
Source Files
¶
- cloudevents_formatter_node.go
- common_keys_values.go
- context.go
- errors.go
- event.go
- event_audit.go
- event_delivery_guarantee.go
- event_error.go
- event_observation.go
- event_sys.go
- event_type.go
- eventer.go
- eventer_config.go
- eventer_retry.go
- hclog_formatter_node.go
- id.go
- options.go
- serialized_writer.go
- sink_config.go
- sink_format.go
- sink_type.go
- testing.go