Skip to content
This repository has been archived by the owner on Nov 8, 2022. It is now read-only.

Commit

Permalink
Correcting case based on common convention:
Browse files Browse the repository at this point in the history
s/snap/Snap/g
  • Loading branch information
mbbroberg committed May 17, 2016
1 parent fb0f412 commit 9ec96eb
Show file tree
Hide file tree
Showing 6 changed files with 35 additions and 35 deletions.
36 changes: 18 additions & 18 deletions docs/PLUGIN_AUTHORING.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The following is a recipe for authoring a plugin that fits smoothly within the s

1. Outline your plugin metrics
2. Decide the CODEC for the plugin
3. Download or clone [snap](https://github.com/intelsdi-x/snap)
3. Download or clone [Snap](https://github.com/intelsdi-x/snap)
4. Download or clone [snap-plugin-utilities](https://github.com/intelsdi-x/snap-plugin-utilities)
5. Implement the required interfaces
6. Test the plugin
Expand All @@ -33,16 +33,16 @@ Like any good recipe, it will do you well to read the entire document, as well a
Bon Appétit! :stew:

## Plugin Authoring
snap itself runs as a master daemon with the core functionality that may load and unload plugin processes via either CLI or HTTP APIs.
Snap itself runs as a master daemon with the core functionality that may load and unload plugin processes via either CLI or HTTP APIs.

A snap plugin is a program, or a set of functions or services, written in Go or any language; that may seamlessly integrate with snap as executables.
A Snap plugin is a program, or a set of functions or services, written in Go or any language; that may seamlessly integrate with snap as executables.

Communication between snap and plugins uses RPC either through HTTP or TCP protocols. HTTP JSON-RPC is good for any language to use due to its nature of JSON representation of data while the native client is only suitable for plugins written in Golang. The data that plugins report to snap is in the form of JSON or GOB CODEC.
Communication between Snap and plugins uses RPC either through HTTP or TCP protocols. HTTP JSON-RPC is good for any language to use due to its nature of JSON representation of data while the native client is only suitable for plugins written in Golang. The data that plugins report to snap is in the form of JSON or GOB CODEC.

Before starting writing snap plugins, check out the [Plugin Catalog](https://github.com/intelsdi-x/snap/blob/master/docs/PLUGIN_CATALOG.md) to see if any suit your needs. If not, you need to reference the plugin packages that defines the type of structures and interfaces inside snap and then write plugin endpoints to implement the defined interfaces.
Before starting writing Snap plugins, check out the [Plugin Catalog](https://github.com/intelsdi-x/snap/blob/master/docs/PLUGIN_CATALOG.md) to see if any suit your needs. If not, you need to reference the plugin packages that defines the type of structures and interfaces inside snap and then write plugin endpoints to implement the defined interfaces.

### Plugin Naming, Files, and Directory
snap supports three type of plugins. They are collectors, processors, and publishers. The plugin project name should use the following format:
Snap supports three type of plugins. They are collectors, processors, and publishers. The plugin project name should use the following format:
>snap-plugin-[type]-[name]
For example:
Expand Down Expand Up @@ -85,7 +85,7 @@ Example:
| /intel/mock/bar.no | not allowed characters | /intel/mock/bar_no |
| /intel/mock/bar!? | not allowed characters | /intel/mock/bar |

snap validates the metrics exposed by plugin and, if validation failed, return an error and not load the plugin.
Snap validates the metrics exposed by plugin and, if validation failed, return an error and not load the plugin.

### Mandatory packages
There are three mandatory packages that every plugin must use. Other than those three packages, you can use other packages as necessary. There is no danger of colliding dependencies as plugins are separated processes. The mandatory packages are:
Expand All @@ -95,26 +95,26 @@ github.com/intelsdi-x/snap/control/plugin/cpolicy
github.com/intelsdi-x/snap/core/ctypes
```
### Writing a collector plugin
A snap collector plugin collects telemetry data by communicating with the snap daemon. To confine to collector plugin interfaces and metric types defined in snap, a collector plugin must implement the following methods:
A Snap collector plugin collects telemetry data by communicating with the Snap daemon. To confine to collector plugin interfaces and metric types defined in Snap, a collector plugin must implement the following methods:
```
GetConfigPolicy() (*cpolicy.ConfigPolicy, error)
CollectMetrics([]MetricType) ([]MetricType, error)
GetMetricTypes(ConfigType) ([]MetricType, error)
```
### Writing a processor plugin
A snap processor plugin allows filtering, aggregation, transformation, etc of collected telemetry data. To complaint with processor plugin interfaces defined in snap, a processor plugin must implement the following methods:
A Snap processor plugin allows filtering, aggregation, transformation, etc of collected telemetry data. To complaint with processor plugin interfaces defined in Snap, a processor plugin must implement the following methods:
```
GetConfigPolicy() (*cpolicy.ConfigPolicy, error)
Process(contentType string, content []byte, config map[string]ctypes.ConfigValue) (string, []byte, error)
```
### Writing a publisher plugin
A snap publisher plugin allows publishing processed telemetry data into a variety of systems, databases, and monitors through snap metrics. To compliant with metric types and plugin interfaces defined in snap, a publisher plugin must implement the following methods:
A Snap publisher plugin allows publishing processed telemetry data into a variety of systems, databases, and monitors through Snap metrics. To compliant with metric types and plugin interfaces defined in Snap, a publisher plugin must implement the following methods:
```
GetConfigPolicy() (*cpolicy.ConfigPolicy, error)
Publish(contentType string, content []byte, config map[string]ctypes.ConfigValue) error
```
### Exposing a plugin
Creating the main program to serve the newly written plugin as an external process in main.go. By defining "Plugin.PluginMeta" with plugin specific settings, the newly created plugin may have its setting to override snap global settings. Please refer to [a sample](https://github.com/intelsdi-x/snap/blob/master/plugin/collector/snap-collector-mock1/main.go) to see how main.go is written. You may browse [snap global settings](https://github.com/intelsdi-x/snap/blob/master/snapd.go#L45-L119).
Creating the main program to serve the newly written plugin as an external process in main.go. By defining "Plugin.PluginMeta" with plugin specific settings, the newly created plugin may have its setting to override Snap global settings. Please refer to [a sample](https://github.com/intelsdi-x/snap/blob/master/plugin/collector/snap-collector-mock1/main.go) to see how main.go is written. You may browse [snap global settings](https://github.com/intelsdi-x/snap/blob/master/snapd.go#L45-L119).

Building main.go generates a binary executable. You may choose to sign the executable with our [plugin signing](https://github.com/intelsdi-x/snap/blob/master/docs/PLUGIN_SIGNING.md).

Expand All @@ -124,14 +124,14 @@ All comments and READMEs within the plugin code should be in English. For diffe
### README
All plugins should have a README with some standard fields:
```
1. snap version requires at least
2. snap version tested up to
1. Snap version requires at least
2. Snap version tested up to
3. Supported platforms
4. Contributor
5. License
```
### Encryption
snap provides the encryption capability for both HTTP and TCP clients. The communication between the snap Daemon and the plugins is encrypted by default. Should you want to disable the encrypted communication, when authoring a plugin, use the `Unsecure` option for your plugin's meta:
Snap provides the encryption capability for both HTTP and TCP clients. The communication between the Snap daemon and the plugins is encrypted by default. Should you want to disable the encrypted communication, when authoring a plugin, use the `Unsecure` option for your plugin's meta:
```
//Meta returns the metadata for MyPlugin
func Meta() *plugin.PluginMeta {
Expand All @@ -140,10 +140,10 @@ func Meta() *plugin.PluginMeta {
```

## Logging and debugging
snap uses [logrus](http://github.com/Sirupsen/logrus) to log. Your plugins can use it, or any standard Go log package. Each plugin has its log file. If no logging directory is specified, logs are in the /tmp directory of the running machine. INFO is the logging level for the release version of plugins. Loggers are excellent resources for debugging. You can also use Go GDB or [delve](https://github.com/derekparker/delve) to debug.
Snap uses [logrus](http://github.com/Sirupsen/logrus) to log. Your plugins can use it, or any standard Go log package. Each plugin has its log file. If no logging directory is specified, logs are in the /tmp directory of the running machine. INFO is the logging level for the release version of plugins. Loggers are excellent resources for debugging. You can also use Go GDB or [delve](https://github.com/derekparker/delve) to debug.

## Building and running the tests
While developing a plugin, unit and integration tests need to be performed. snap uses [goconvery](http://github.com/smartystreets/goconvey/convey) for unit tests. You are welcome to use it or any other unit test framework. For the integration tests, you have to set up $SNAP_PATH and some necessary direct, or indirect dependencies. Using Docker container for integration tests is an effective testing strategy. Integration tests may define an input workflow. Refer to a sample [integration test input](https://github.com/intelsdi-x/snap/blob/master/examples/configs/snap-config-sample.json).
While developing a plugin, unit and integration tests need to be performed. Snap uses [goconvery](http://github.com/smartystreets/goconvey/convey) for unit tests. You are welcome to use it or any other unit test framework. For the integration tests, you have to set up $SNAP_PATH and some necessary direct, or indirect dependencies. Using Docker container for integration tests is an effective testing strategy. Integration tests may define an input workflow. Refer to a sample [integration test input](https://github.com/intelsdi-x/snap/blob/master/examples/configs/snap-config-sample.json).

For example, to run a plugin integration test
```
Expand All @@ -156,7 +156,7 @@ For more build and test tips, please refer to our [contributing doc](https://git
If you think others would find your plugin useful, we encourage you to submit it to our [Plugin Catalog](https://github.com/intelsdi-x/snap/blob/master/docs/PLUGIN_CATALOG.md) for possible inclusion.

## License
Project snap is released under the Apache 2.0 license.
The Snap framework is released under the Apache 2.0 license.

## For more help
Please browse more at our [repo](https://github.com/intelsdi-x/snap) or contact snap [maintainers](https://github.com/intelsdi-x/snap#maintainers).
Please browse more at our [repo](https://github.com/intelsdi-x/snap) or contact the [maintainers](https://github.com/intelsdi-x/snap#maintainers).
4 changes: 2 additions & 2 deletions docs/PLUGIN_SIGNING.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
Plugin Signing
==============
# Security
By default, the snap daemon (snapd) has plugin signing verification enabled. To disable it or turn it to warning, the flag `--plugin-trust, -t` can be set to 0 or 2 respectively.
By default, the Snap daemon (snapd) has plugin signing verification enabled. To disable it or turn it to warning, the flag `--plugin-trust, -t` can be set to 0 or 2 respectively.

##How it works
![How it works](https://cloud.githubusercontent.com/assets/12282848/10112575/19bec0f4-6391-11e5-8f27-7a1a057122fd.png)
Private/public keys and keyrings are generated by GPG. The plugin is signed with the private key and the public key needs to be added to the user's keyring. The signing is an armored detached signature in the form of a `.asc` file.

The snap daemon uses the [Golang OpenPGP library](https://godoc.org/golang.org/x/crypto/openpgp)'s `CheckArmoredDetachedSignature` function to validate the signature using the keyring, plugin, and signature file before loading the plugin. It checks the issuer key ID, hash, and signature type.
The Snap daemon uses the [Golang OpenPGP library](https://godoc.org/golang.org/x/crypto/openpgp)'s `CheckArmoredDetachedSignature` function to validate the signature using the keyring, plugin, and signature file before loading the plugin. It checks the issuer key ID, hash, and signature type.
```go
openpgp.CheckArmoredDetachedSignature(keyring, signed, signature)
```
Expand Down
10 changes: 5 additions & 5 deletions docs/REST_API.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# snap API
snap exposes a list of RESTful APIs to perform various actions. All of snap's API requests return `JSON`-formatted responses, including errors. Any non-2xx HTTP status code may contain an error message. All API URLs listed in this documentation have the endpoint:
# Snap API
Snap exposes a list of RESTful APIs to perform various actions. All of Snap's API requests return `JSON`-formatted responses, including errors. Any non-2xx HTTP status code may contain an error message. All API URLs listed in this documentation have the endpoint:
> http://localhost:8181
## API Response Meta
Expand Down Expand Up @@ -216,7 +216,7 @@ _**Example Response**_
}
```
## Metric API
snap metric APIs allow you to retrieve all or particular running metric information by invoking different APIs.
Snap metric APIs allow you to retrieve all or particular running metric information by invoking different APIs.

## Metric Response Parameters
| Parameter | Description |
Expand Down Expand Up @@ -331,7 +331,7 @@ _**Example Response**_
}
```
## Task API
snap task APIs provide the functionality to create, start, stop, remove, enable, retrieve and watch scheduled tasks.
Snap task APIs provide the functionality to create, start, stop, remove, enable, retrieve and watch scheduled tasks.

### Task API Response Parameters
| Parameter | Description |
Expand Down Expand Up @@ -612,7 +612,7 @@ _**Example Response**_
}
```
## Tribe API
snap tribe APIs provide the functionality for managing tribe agreements and for tribe members to join or leave tribe contracts.
Snap tribe APIs provide the functionality for managing tribe agreements and for tribe members to join or leave tribe contracts.

### Tribe API Response Parameters
| Parameter | Description |
Expand Down
2 changes: 1 addition & 1 deletion docs/SNAPD.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ limitations under the License.
-->

# snapd
The snap daemon/agent (snapd) is a modular application that consists of a control module, a scheduler module, and a REST API. The control module is responsible for loading and unloading plugins, managing loaded plugins, and maintaining an available pool of running plugins for running tasks. The scheduler module is responsible for running the workflows in created tasks per the schedule stated. The REST API provides an interface for loading and unloading plugins, creating and removing tasks, starting and stopping tasks, and listing metrics available for collection.
The Snap daemon/agent (snapd) is a modular application that consists of a control module, a scheduler module, and a REST API. The control module is responsible for loading and unloading plugins, managing loaded plugins, and maintaining an available pool of running plugins for running tasks. The scheduler module is responsible for running the workflows in created tasks per the schedule stated. The REST API provides an interface for loading and unloading plugins, creating and removing tasks, starting and stopping tasks, and listing metrics available for collection.

## Usage
```
Expand Down
12 changes: 6 additions & 6 deletions docs/SNAPD_CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ In order of precedence (from greatest to least):
- Default values per configuration setting

## Usage
The configuration file is comprised of different sections for each module that the snap daemon can run. Settings specifically for the snap daemon are defined on the top level, along with configuration sections for Control, Scheduler, REST API Server, and Tribe. Below, each section will be detailed in YAML format broken out for each section. A full example configuration file can be seen in YAML or JSON format in examples/configs in the project source.
The configuration file is comprised of different sections for each module that the Snap daemon can run. Settings specifically for the Snap daemon are defined on the top level, along with configuration sections for Control, Scheduler, REST API Server, and Tribe. Below, each section will be detailed in YAML format broken out for each section. A full example configuration file can be seen in YAML or JSON format in examples/configs in the project source.

## YAML Example
When defining a configuration in YAML format, options or sections can be commented out if the value provided will not be different from the default value configured by the system.

### snapd configuration
This section comprises of configuration settings that are specific for the snap daemon.
This section comprises of configuration settings that are specific for the Snap daemon.

```yaml
---
Expand All @@ -57,7 +57,7 @@ gomaxprocs: 1
```
### snapd control configurations
The control section contains settings for configuring the Control module within the snap daemon. These configuration settings are specific for the running of plugins and the plugins section under control allows for passing of plugin specific configuration items to the plugins during a task run.
The control section contains settings for configuring the Control module within the Snap daemon. These configuration settings are specific for the running of plugins and the plugins section under control allows for passing of plugin specific configuration items to the plugins during a task run.
```yaml
control:
Expand Down Expand Up @@ -123,7 +123,7 @@ control:
```
### snapd scheduler configurations
The scheduler section of the configuration file configures settings for the Scheduler module inside the snap daemon.
The scheduler section of the configuration file configures settings for the Scheduler module inside the Snap daemon.
```yaml
scheduler:
Expand All @@ -137,7 +137,7 @@ scheduler:
```
### snapd REST API configurations
The restapi section of the configuration file configures settings for enabling and running the REST API as part of the snap daemon. The snapctl command line tool uses the REST API to manage snapd on a host.
The restapi section of the configuration file configures settings for enabling and running the REST API as part of the Snap daemon. The snapctl command line tool uses the REST API to manage snapd on a host.
```yaml
restapi:
Expand Down Expand Up @@ -168,7 +168,7 @@ restapi:
```
### snapd tribe configurations
The tribe section of the configuration file configures settings for enabling and running tribe as part of the snap daemon.
The tribe section of the configuration file configures settings for enabling and running tribe as part of the Snap daemon.
```yaml
tribe:
# enable controls enabling tribe for the snapd instance. Default value is false.
Expand Down
Loading

0 comments on commit 9ec96eb

Please sign in to comment.