fluent-plugin-pagerduty 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96e70bdf4f296d3d857f89dbd2bb8938cb8b859e
-  data.tar.gz: 1aee8fba1aca9fc563c819c7e262623fe4366acc
+  metadata.gz: 3e1ab17de590fac6a23aca6395aaacbad6e895a6
+  data.tar.gz: 4c57cc67becf6ca2fd81dcf7ab99b3a3987eb48b
 SHA512:
-  metadata.gz: 8787ed0e0f46fc14f5aaf7efbf2b1662cb439e9bf68ced78b65de5b507e2d2d2e46a22ebd25ef232040c1e4181ac7217e04ec53d0f56f6e7107237898c2e7f8e
-  data.tar.gz: 26c760145fa0902f8856bf2ebf23e24e54136c813a9de17ca61270956e083b62c12c9ac8580d951a4b3c973055b535e7d90333b9f478220724870a767604094c
+  metadata.gz: 3d4c97238f8765492974989bc7fbe6149434a6855769123879c1a8ad0010d6fd1d5f484100174319bfed8d138d3da7a3e29f4ed0c78046509d258be5396a92de
+  data.tar.gz: cf500b232f2f5807d9515125f0b7c36df8b95b0ec4c8251b2afe0c0bfc7cd545de6e9bdb5dbc102494e6f3e355c7598222d85f034a5e3ca6aa74189bbe7c0a55

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 vendor/*
+*.DS_Store

data/README.md

@@ -1,24 +1,26 @@
-# fluent-plugin-pagerduty does not work
+# fluent-plugin-pagerduty
 
 Fluentd Output plugin to relay alert notification from application to [PagerDuty](http://www.pagerduty.com/).
 
 ## Installation
 
-install with `gem` or `fluent-gem` command as:
+install with `td-agnet-gem` or `fluent-gem`, `gem` command as:
 
 ```
-# for fluentd
-$ gem install fluent-plugin-pagerduty
+# for td-agent2 (recommend)
+$ sudo td-agent-gem install fluent-plugin-pagerduty -v 0.0.1
 
 # for td-agent
 $ sudo /usr/lib64/fluent/ruby/bin/fluent-gem install fluent-plugin-pagerduty -v 0.0.1
 
-# for td-agent2
-$ sudo td-agent-gem install fluent-plugin-pagerduty -v 0.0.1
+# for system installed fluentd
+$ gem install fluent-plugin-pagerduty
 ```
 
 ## Usage
 
+<img width="1025" alt="screenshot 2017-03-18 18 20 43" src="https://cloud.githubusercontent.com/assets/1428486/24077350/ab9f9dd4-0c07-11e7-9f9f-8cd27a451b6e.png">
+
 1. add service selecting `Service Type : Generic API system` on PagerDuty websites
 2. copy API Key from the `Services` page.
 3. install fluent-plugin-pagerduty with gem or fluent-gem command.
@@ -26,15 +28,19 @@ $ sudo td-agent-gem install fluent-plugin-pagerduty -v 0.0.1
 5. restart fluentd process.
 6. send test message for fluent-plugin-pagerduty
 
-#### configuration example
+### Examples
+
+#### Simple alert (JSON pass-thru)
+
+In this example, a JSON record already conforming to the PagerDuty API is processed by Fluentd and passed through to PagerDuty as-is, triggering a simple alert.
 
 ```
 <source>
-  type forward
+  @type forward
 </source>
 
 <source>
-  type http
+  @type http
   port 8888
 </source>
 
@@ -44,8 +50,6 @@ $ sudo td-agent-gem install fluent-plugin-pagerduty -v 0.0.1
 </match>
 ```
 
-#### notify example
-
 ```
 # via forward
 $ echo '{"description":"Form validation has failed","details":{"name":"success","mail":"failed"}}' | fluent-cat notify.pagerduty
@@ -54,6 +58,70 @@ $ echo '{"description":"Form validation has failed","details":{"name":"success",
 $ curl http://localhost:8888/notify.pagerduty -F 'json={"description":"Form validation has failed","details":{"name":"success","mail":"failed"}}'
 ```
 
+#### Advanced alert (transformed JSON)
+
+In this example, a JSON record is referenced to build a PagerDuty event with an incident key for managing [de-duplication](https://v2.developer.pagerduty.com/docs/events-api#incident-de-duplication-and-incident_key).
+
+```
+<source>
+  @type forward
+</source>
+
+<source>
+  @type http
+  port 8888
+</source>
+
+<match notify.pagerduty>
+  type pagerduty
+  service_key   ******************
+  description   Alarm@${Node["Location"]}:: ${Log["Message"]}
+  incident_key  [${tag_parts[-1]}] ${Log["File"]}:${Log["Line"]}
+</match>
+```
+
+```
+# via forward
+$ echo '{"Node":{"Location":"Somewhere","IP Address":"10.0.0.1"},"Log":{"Level": "ERROR","File":"FooBar.cpp","Line":42,"Message":"A very important logging message"}}' | fluent-cat notify.pagerduty
+
+# via http
+$ curl http://localhost:8888/notify.pagerduty -F 'json={"Node":{"Location":"Somewhere","IP Address":"10.0.0.1"},"Log":{"Level": "ERROR","File":"FooBar.cpp","Line":42,"Message":"A very important logging message"}}'
+```
+
+
+### Option Parameters
+
+- `service_key` (required)
+
+    The unique API identifier generated for each PagerDuty service belonging to a PagerDuty account. Must be present for any PagerDuty events.
+
+- `event_type` (optional)
+
+    The PagerDuty event type: `trigger`, `acknowledge`, or `resolve`. If unspecified, the default is `trigger`.
+
+- `description` (conditionally required)
+
+    The message content of a PagerDuty event. PagerDuty event types of `trigger` must contain a description. The content of the description may be built using Placeholders (see next section).
+
+- `incident_key` (optional)
+
+    The identifier used for PagerDuty's [de-duplication of events](https://v2.developer.pagerduty.com/docs/events-api#incident-de-duplication-and-incident_key). The content of the incident key may be built using Placeholders (see next section).
+
+### Placeholders
+
+These placeholders are available:
+
+* ${…}
+  * `hashName["key"]` Value of `key` in named hash
+  * `arrayName[N]` Value at index _N_ in named array
+  * `primitive` Value of named primitive
+  
+    Placeholders are built recursively and concatenated. For example, a specific value within a hash containing an array of hashes could be referenced as: `${foo["bar"][2]["baz"]}`.
+* ${tag} Input tag
+* ${tag\_parts[N]} Input tag splitted by '.' indexed with _N_ such as `${tag_parts[0]}`, `${tag_parts[-1]}`. 
+
+Placeholder functionality is derived from features of [fluent-plugin-record-reformer](https://github.com/sonots/fluent-plugin-record-reformer).
+
 ## Contributing
 
 1. Fork it
@@ -72,5 +140,5 @@ Copyright (c) 2013- Kentaro Yoshida (@yoshi_ken)
 
 ## License
 
-Apache License, Version 2.0
+[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
 

data/fluent-plugin-pagerduty.gemspec

@@ -4,10 +4,9 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "fluent-plugin-pagerduty"
-  spec.version       = "0.0.1"
+  spec.version       = "0.1.0"
   spec.authors       = ["Kentaro Yoshida"]
   spec.email         = ["y.ken.studio@gmail.com"]
-  spec.description   = %q{Fluentd Input plugin to replay alert notification for PagerDuty API.}
   spec.summary       = %q{Fluentd Input plugin to replay alert notification for PagerDuty API.}
   spec.homepage      = "https://github.com/y-ken/fluent-plugin-pagerduty"
   spec.license       = "Apache License, Version 2.0"

data/lib/fluent/plugin/out_pagerduty.rb

@@ -9,34 +9,137 @@ class Fluent::PagerdutyOutput < Fluent::Output
   config_param :service_key, :string, :default => nil
   config_param :event_type, :string, :default => 'trigger'
   config_param :description, :string, :default => nil
+  config_param :incident_key, :string, :default => nil
 
   def configure(conf)
     super
 
+    # API requires service key
     if @service_key.nil?
       $log.warn "pagerduty: service_key required."
     end
+
+    # PagerDuty trigger event type requires description, other event types do not
+    if @event_type == 'trigger' && @description.nil?
+      $log.warn "pagerduty: description required for trigger event_type."
+    end
   end
 
   def emit(tag, es, chain)
     es.each do |time,record|
-      call_pagerduty(record)
+      call_pagerduty(tag, record)
     end
 
     chain.next
   end
 
-  def call_pagerduty(record)
+  def call_pagerduty(tag, record)
     begin
+      expander = PlaceholderExpander.new({:log => log})
+      tag_parts = tag.split('.')
+      placeholder_values = {
+        'tag'       => tag,
+        'tag_parts' => tag_parts,
+        'record'    => record,
+      }
+
+      placeholders = expander.prepare_placeholders(placeholder_values)
+      
       service_key = record['service_key'] || @service_key
       event_type = record['event_type'] || @event_type
       description = record['description'] || record['message'] || @description
+      incident_key = record['incident_key'] || @incident_key
       details = record['details'] || record
       options = {"details" => details}
-      api = Pagerduty.new(service_key)
+      
+      description = expander.expand(description, placeholders)
+      
+      if !@incident_key.nil?
+        incident_key = expander.expand(incident_key, placeholders)
+        api = PagerdutyIncident.new(service_key, incident_key)
+      else
+        api = Pagerduty.new(service_key)
+      end
+
       incident = api.trigger description, options
     rescue => e
       $log.error "pagerduty: request failed. ", :error_class=>e.class, :error=>e.message
     end
   end
 end
+
+
+# Modified PlaceholderExpander borrowed from fluent-plugin-record-reformer
+# https://github.com/sonots/fluent-plugin-record-reformer
+# Original author: Naotoshi Seo
+# MIT License: https://github.com/sonots/fluent-plugin-record-reformer/blob/master/LICENSE
+# Modifications: Michael Karlesky
+# Changes:
+#  - Stripped down to limited use case
+#  - Building of placeholders is now recursive to handle any depth of hash, array, and primitive
+class PlaceholderExpander
+  attr_reader :placeholders, :log
+
+  def initialize(params)
+    @log = params[:log]
+  end
+
+  def prepare_placeholders(placeholder_values)
+    placeholders = {}
+
+    placeholder_values.each do |key, value|
+      # For any entry in `placeholder_values` that is a hash, we effectively ignore its internal name.
+      # For example, `record` is an important hash, but referencing it at the top-level is superfluous namespacing.
+      # Instead of '${record["Node"]["Location"]}',
+      #  '${Node["Location"]}' more closely maps to a user's knowledge of a data to be processed.
+      if value.kind_of?(Hash)
+        value.each do |key, value|
+          build_placeholders(placeholders, key, value)
+        end
+      else
+        build_placeholders(placeholders, key, value)        
+      end
+    end
+
+    placeholders
+  end
+
+  # Expand string (`${foo["bar"]}`) with placeholders
+  def expand(str, placeholders)
+    single_placeholder_matched = str.match(/\A(\${[^}]+}|__[A-Z_]+__)\z/)
+    if single_placeholder_matched
+      log_if_unknown_placeholder($1, placeholders)
+      return placeholders[single_placeholder_matched[1]]
+    end
+    str.gsub(/(\${[^}]+}|__[A-Z_]+__)/) {
+      log_if_unknown_placeholder($1, placeholders)
+      placeholders[$1]
+    }
+  end
+
+  private
+
+  # Recurses to build any depth of hash, arrays, and primitives
+  def build_placeholders(placeholders, key, value)
+    if value.kind_of?(Array) # tag_parts, etc
+      size = value.size
+      value.each_with_index do |v, idx|
+        build_placeholders(placeholders, "#{key}[#{idx}]", v)
+        build_placeholders(placeholders, "#{key}[#{idx-size}]", v) # support [-1]
+      end
+    elsif value.kind_of?(Hash) # record, etc
+      value.each do |k, v|
+        build_placeholders(placeholders, %Q[#{key}["#{k}"]], v) # record["foo"]
+      end
+    else
+      placeholders.store("${#{key}}", value)
+    end
+  end
+
+  def log_if_unknown_placeholder(placeholder, placeholders)
+    unless placeholders.include?(placeholder)
+      log.warn "pagerduty: unknown placeholder `#{placeholder}` found"
+    end
+  end
+end
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fluent-plugin-pagerduty
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Kentaro Yoshida
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-19 00:00:00.000000000 Z
+date: 2018-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,7 +66,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Fluentd Input plugin to replay alert notification for PagerDuty API.
+description: 
 email:
 - y.ken.studio@gmail.com
 executables: []