Users have expressed a wish for helpers for commonly-specified TLS attributes, such as CA certificates.

Any annotations read from agent.yml are automatically downcased, so we should figure out if it's possible to load these annotations in plugins which require them. Presently we recommend camelCase annotation keys in docs, and these are silently downcased only in the case of loading from agent.yml. If a camelCase key is already present on the entity, loading the same key regardless of case will cause the camelCase key to be overwritten by a lowercase key.

I'm not sure the best way to address this, but here's the problem.

because Execute() eventually calls exitFunction which defaults to os.Exit the main() function pattern as used in the template plugin github projects are very difficult to test using go test
What happens is main() will exit the test entirely unless you set exitFunction, but exitFunction isn't exposed as a tunable.

I'm able to work-around this using reflect and unsafe golang packages but that seems like a lot of work to support some basic testing that we need all derived plugins to be doing.
Example workaround: https://github.com/sensu/sensu-kafka-handler/blob/master/main_test.go

Straw proposal, extend the interface that exposes Execute, with a setter function for exitFunction.

I want to include event IDs in notifications, e.g. providing the uuid form of the ID in an email for debugging purposes.

Using the email handler template capability, I can create emails using the template Event ID: {{ .ID }} but this is a slice of bytes and is rendered in the resulting email as Event ID: [209 148 75 68 153 63 79 30 190 227 200 57 207 112 180 28]

I believe the UUID representation can be created from a slice of bytes using https://godoc.org/github.com/google/uuid#FromBytes .

The SDK implements some helpers for rendering templates, e.g. UnixTime template function. I propose we add a UUIDFromBytes template function which would make the above linked function available to handlers using the SDK.

Problem

Annotation overrides for StringSlice arguments assume a json encoding instead of using the space delimited behavior used in the arguments and environment variables.

Let's make arguments parse in a more consistent manner.

Straw proposal

1. Arguments of cobra StringSlice type use CSV styled space delimited in al contexts.
2. Arguments of cobra StringArray type are parsed in ENV and annotation as a json array of strings, if not parsable as json assume its a single string.

Hi Sensu team,

I see that the handler execution is stateless, but in some use cases it's useful to keep a state between two executions. Is there any existing solution for this use case?

If not, do you think it's something that might be implemented in the future?

Thank you

Add a Required attribute to PluginConfigOption, which would automatically ensure that the option was provided, so plugins developer don't have manually loop through options to make sure they were indeed provided.

Problem:

go get: github.com/sensu-community/sensu-plugin-sdk@none updating to
	github.com/sensu-community/[email protected]: parsing go.mod:
	module declares its path as: github.com/sensu/sensu-plugin-sdk
	        but was required as: github.com/sensu-community/sensu-plugin-sdk

One of the places:

https://github.com/sensu/sensu-plugin-sdk/search?q=sensu-community

Add a version command that will output version information that can be set via ldflags. By default, the following are used by goreleaser:

-X main.version={{.Version}}
-X main.commit={{.Commit}}
-X main.date={{.Date}}
-X main.builtBy=goreleaser

Currently:
currently string slice arguments are handled as pflags.StringSlice and this treats strings as CSV comma delimited strings making it possible to use a single argument call and extract a multiple value string slice from a single string.
Problem:
Automatic use of commas as separates is not always appropriate

Solution:
optionally allow arguments to be treated as pflags.StringArray, which does not automatically used the comma delimited string splitting.

Straw Implementation:
Extend the option struct with a new boolean to treat string slice as a pflags.StringArray in setupFlag() function

Prior to cutting the 0.16 tag, need to update the examples in the Readme to match the refactored options syntax.

Feature Description

Check plugin use case

Prometheus exposition format is desirable across several metric check plugins, it would be useful to have a set of SDK functions that check plugins could make use of for consistent well formed Prometheus exposition output instead of having each plugin roll its own process.

Handler plugin use case

Sensu handlers based on this SDK would also benefit from helper function that know how to take Sensu internal metrics format and convert them into Prometheus exposition in a consistent manner.

Considerations

1. Prometheus metrics exposition format makes use of specially formatted unique comment strings to provide type information decorating a family of related metrics. These comment strings can only show up once per metrics family group.
2. Sensu agent ingests Prometheus exposition format and converts the comments into specially named Sensu metrics tags that appear on all metrics. To support the handler use case, SDK metrics helper function would need to set/comprehend specially named tags consistent with how sensu-agent currently does the task.

Straw Implementation

Helper function to populate Sensu Metrics object programmatically

Helper function must be able to store optional TYPE and HELP comments consistent with how Sensu Agent ingests prom exposition metrics.

Check plugin use case

Check plugin executable would use this function to populate a Sensu Metrics structure as part of metrics collection business logic.

Handler plugin use case

Handlers are not expected to need this function

Helper function to output Sensu Metrics in prom exposition format

Helper function must be able to take Sensu Metrics object and export it in prometheus exposition formatted string building TYPE and HELP comment strings from Metrics tag information consistent with how sensu-agent currently ingests prometheus comment strings.

Check plugin use case

Check plugin executable would use this function to export metrics collected into Sensu Metrics object as Prometheus exposition formatted string.

Handler plugin use case

Handler plugin executable would use this function to export Sensu Metrics object as Prometheus exposition formatted string.

Minimum Viable Goal

1. Need to be able to refactor system-check plugin to use these helper functions to create prom exp output:

./system-check 
# HELP system_cpu_cores [GAUGE] Number of cpu cores on the system
# TYPE system_cpu_cores GAUGE
system_cpu_cores{} 8 1636582440402
# HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle
# TYPE system_cpu_idle GAUGE
system_cpu_idle{cpu="cpu0"} 74.49664429582639 1636582440402
system_cpu_idle{cpu="cpu1"} 78.26086956470425 1636582440402
system_cpu_idle{cpu="cpu2"} 77.07641196137524 1636582440402
system_cpu_idle{cpu="cpu3"} 81.27090300950525 1636582440402
system_cpu_idle{cpu="cpu4"} 76.8456375843412 1636582440402
system_cpu_idle{cpu="cpu5"} 78.1144781152644 1636582440402
system_cpu_idle{cpu="cpu6"} 81.72757475139935 1636582440402
system_cpu_idle{cpu="cpu7"} 81.33333333413934 1636582440402
system_cpu_idle{cpu="cpu-total"} 78.56247388180051 1636582440402
# HELP system_cpu_used [GAUGE] Percent of time all cpus were used
# TYPE system_cpu_used GAUGE
system_cpu_used{cpu="cpu0"} 25.503355704173615 1636582440402
system_cpu_used{cpu="cpu1"} 21.73913043529575 1636582440402
system_cpu_used{cpu="cpu2"} 22.923588038624757 1636582440402
system_cpu_used{cpu="cpu3"} 18.729096990494753 1636582440402
system_cpu_used{cpu="cpu4"} 23.154362415658795 1636582440402
system_cpu_used{cpu="cpu5"} 21.885521884735596 1636582440402
system_cpu_used{cpu="cpu6"} 18.272425248600655 1636582440402
system_cpu_used{cpu="cpu7"} 18.66666666586066 1636582440402
system_cpu_used{cpu="cpu-total"} 21.437526118199486 1636582440402
...

2. Need to be able to refactor sumologic handler plugin using the same helper functions to take event generated from system-check and ingested by sensu-agent and faithfully reproduce original prom exp format string.

I find PluginConfigOption kind of confusing, especially with PluginConfig around; its name led me to believe it had a direct link with the plugin configuration.

Not sure what's the best solution from that point, here's some ideas:

• Rename PluginConfig to PluginCommand
• Rename PluginConfigOption to...
  • PluginInput
  • PluginOption
  • PluginFlag
  • PluginArg
  • etc.

sprig provides some great functionality for manipulating strings, dates, etcd as part of golang templates.

great for any plugin that needs to use a configurable template string.

New argument types need to be supported to provide more flexibility to plugin developers. The following argument types should be supported.

• uint16
• uint32
• int16
• int32
• int64
• float32
• float64

Extract Sensu Go license validation logic from the commercial distribution of Sensu and place it in a new project repository, sensu/sensu-licensing. Update the SDK to import the licensing project and support optional license enforcement for Handlers. Update the commercial distribution of Sensu to import and use the licensing project. Handler plugin authors can then choose to require a valid license for plugin execution or partial functionality (good signature and valid until timestamp). The commercial distribution of Sensu Go will soon expose a cluster's active license file to handler plugins via an environment variable, SENSU_LICENSE_FILE. The license file is JSON encoded. This work will result in a new release of the SDK.

Proposal document: https://docs.google.com/document/d/1tHKIyx7kCetxwfpWfjUUlJCK9cpOiNrk2NWGgwLw8rQ/edit#

Following up on #60

Rationale

Some check patterns require a small amount of state for correct operation. Lets bake that functionality into the SDK.

Check State Use Cases

• log checking -> to keep up with file seek location to optimize log file reading
• rate threshold checks -> many existing check threshold patterns currently require checks to internally wait and call an operation twice in order to calculate a rate. This behavior could be better optimized if the sdk kept a state file to be used.

Implementation requirements derived from current sensu-log-check implementation

Operational requirements/assumptions

• Must assume the same plugin executable may be run with different settings on the same agent as different checks or check hooks, and each will need a different state file.
• State file is a single access at a time.
• State file contents must be able to represent a json-like golang struct with nested maps and slices.

Basic functionality needed

1. Function to read state filepath into corresponding golang struct pointer

• return nil if state file is missing or empty
• return error if read permission error or similar

2. Function to write golang struct pointer into state file

• silently create file if missing.
• return error if write permission error or similar

Advanced Functionality

If possible, implement state file with client access locking aware so that check can hold a lock on the file while the check is operating preventing a second check from access the file. This will prevent operators from accidentally using the same state file for multiple independently running checks or check hooks.

Hypothetical plugin check operation with locking

1. Pass state filepath as cmdline argument and save into plugin level attribute
2. Establish state file session enabling file access lock automatically at start of check execution function, defer session close as part of check execution function as part of normal SDK operation.
3. Read state filepath contents and hold in golang struct pointer as part of check execution business logic.
4. Perform additional check operation business logic
5. Write golang state struct pointer into state filepath as part of check execution business logic
6. Perform remaining chec operation business logic
7. run deferred close state file session dropping the client access lock at check execution end

I believe we could decrease the number of decisions a plugin developer needs to do when using this SDK, by enforcing some conventions, and therefore simplify the process of creating your own plugin.

For example, the various NewGo... (e.g. sensu.NewGoHandler) require you to pass functions as arguments:

func main() {
	handler := sensu.NewGoHandler(&handler.PluginConfig, options, checkArgs, executeHandler)
	handler.Execute()
}

func checkArgs(_ *types.Event) error {}

func executeHandler(event *types.Event) error {}

I believe by adopting some conventions on the name of these functions, we could reduce the number of arguments required and therefore the complexity. For example, if we assumed that a Plugin must adhere to a given interface, we could simply do the following instead:

func main() {
	handler := sensu.NewGoHandler(&plugin)
	handler.Execute()
}

func (p *Plugin) Validate(_ *types.Event) error {}

func (p *Plugin) Execute(event *types.Event) error {}

Similarly, I don't believe declaring a PluginConfigOption should require that much attributes, e.g.

&sensu.PluginConfigOption{
			Path:      "example",
			Env:       "HANDLER_EXAMPLE",
			Argument:  "example",
			Shorthand: "e",
			Default:   "",
			Usage:     "An example configuration option",
			Value:     &handler.endpoint,
		},
	}

Instead, maybe we could simply assume sane default values (e.g. I assume the Path and the Argument could be similar) but allow those values to be overridden for edge cases.

Make it possible for the sdk to communicate the keyspace in the help message.

Straw proposal:

override the cobra.command default HelpFunction with a custom function that appends a Keyspace usage string into the the help output.

Right now go.mod pins some random commit from May 2019. It should probably reference a sensu-go release?

The first version of this repository contains an abstraction for the common Sensu handler logic. The abstraction is responsible to

• Read and validate the Sensu event from stdin
• Read the arguments from the command line, environment variable or Sensu event
• Execute the user provided validation logic
• Execute the user provided handler logic

We want to implement a similar pattern for Sensu checks. While handlers and checks are similar there are some differences (please correct me if I'm wrong).

• Handlers read a Sensu Event from stdin while Checks don't
• Handlers always read a Sensu Event from stdiin while checks optionally read one
• Handlers can read input values from the event, while checks can't since they don't read an event
• Checks write the return the result data to stdout or stderr, handlers don't
• Checks exit status code indicates the state... 0=OK, 1=WARNING, 2=CRITICAL, other=UNKNOWN

You can look at the gohandler.go file, as some code can probably be reused. What I had in mind is to invoke the checks the same way the handlers are with some subtle differences.

1. See the way options are defined at https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31. Very similar approach but no need to have the Path property since it defines where to look in the Sensu Event.
2. Create a new sensu.NewGoCheck function instead of sensu.NewGoHandler https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31
3. The sensu.NewGoCheck function should have an extra readSensuEvent argument which would tell whether or not the Sensu Check expects an event to be sent through stdin
4. The execution method needs to have a way to return the exit status code, result and error. The result and error should automatically be written to stdout and stderr respectively. The exit status code should be used automatically when the check process exits. Signature might be something like this: func(event *types.Event) (int, string, error) - (exit status code, result, error) where event will be nil if the check doesn't read from stdin

Unit tests are required.

Once this is done the EC2 plugin can be converted to use the abstraction.

See: https://github.com/sensu-community/sensu-plugin-sdk/blob/master/go.mod#L6

Current Problem

Right now we don't have a consistent way to expose which argument are backed by environment variables.

Straw Proposals

two possible implementations

1. extend the usage message to include a table of these mappings
2. extend plugin with a command to describe the supported envvars

Checks

• 0 indicates “OK”
• 1 indicates “WARNING”
• 2 indicates “CRITICAL”

Mutators

• 0 indicates OK status
• exit codes other than 0 indicate failure

Handlers

No mention, assuming the same as mutators

Want:
keyspace-describe command similar to how version command works that will give details about the annotation keyspace and the argument paths configured.

Right now its really hard to get help or to document how the keyspace paths work. Let's make that easier for everyone.

Problem Statement

base plugin pluginWorkflowFunction will always trigger the usage message if a non nil error is returned.

But in practice objects built on top of base plugin such as GoHandler and GoCheck have separate validation and execute functions.

Example GoHandler

Typically you want errors from GoHandler's validationFunction to trigger a usage message as the validationFunction is used for ensuring correct argument usage, and the usage message as output for failures there make sense as a breadcrumb for users to help them find the solution to the problem when using plugin as an asset.

But, when GoHandler's executeFunction returns an error you typically just want the error output, not the usage message, as the usage message in this context just adds noise.

Straw Enhancement Proposal

Extend base plugin's pluginWorkflowFunction to return additional boolean to indicate if usage message needs to be displayed.
Refactor derived plugin types to use new usage message boolean logic.

Pending sensu/sensu-go#4875, we will need to rename our api/core/vX and types imports.

Likely warrants a major version bump.

When displaying --help output whether intentionally or when an error has occurred, if a secret is present as an environment variable assignable in PluginConfigOption, it could possibly be leaked.

One possible solution would be to add a PluginConfigOption boolean called 'secret' that when set to true would not print the default values in those cases.

We need to add documentation to all types exported by the SDK!

Create an abstraction to execute Sensu Mutators (https://docs.sensu.io/sensu-go/5.5/reference/mutators/). Mutators accept a Sensu event, transform the event and returns the output JSON.

The first version of this repository contains an abstraction for the common Sensu handles logic. The abstraction is responsible to

• Read and validate the Sensu event from stdin
• Read the arguments from the command line, environment variable or Sensu event
• Execute the user provided validation logic
• Execute the user provided handler logic

We want to implement something similar for mutators.

The similarities and differences are:

• Mutators and handlers both read a Sensu event from stdin
• Mutators and handlers both read command line and env variable arguments
• Do we want to support configuration overrides in the mutators? @calebhailey
• Mutators return the transformed event's JSON to stdout or stderr
• Mutators return a 0 exit status code upon success or any other in case of failure

How to implement

1. See the way options are defined at https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31. Very similar approach but no need to have the Path property since it defines where to look in the Sensu Event. Dependent on the support of configuration overrides
2. Create a new sensu.NewGoMutator method instead of sensu.NewGoHandler https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31
3. The validation method signature should be the same - https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31
4. The execution method should return an interface object with JSON annotations, or an error - https://github.com/sensu-skunkworks/sensu-aws-ec2-deregistration-handler/blob/sensu-auth/main.go#L31 Signature might be something like func(event *types.Event) (*types.Event, error)
5. If no error is present the exit status code is automatically set to 0, otherwise it is set to 1

Unit tests are required.

This appears to be a regression in v0.16 from previous releases, not sure how far back this goes.

When passing a bad argument for example "--gross icky" the output reads "Error executing blah-blah-plugin: unknown flag: --gross" but the return status is 0.

The return status should definitely be non-zero to help plugin users diagnose the problem.

This isn't solvable inside the plugins using the sdk. The sdk actually forces exits prior to any plugin specific business logic runs such as a checkArgs function

Recently, a community user attempted to use the HTTP client, but was unable to, because the client sends POST requests to the incorrect URL.

The issue is that the library uses a URL generated in part by URIPath, which includes the namespace and name of the resource. However, when targeting routes with POST, this results in incorrect paths.

The library should handle these situations gracefully and come up with the correct URL when instructed to use POST.