grafana 0.8.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1eeaff5e0d8939a347d5a71c63c189f814caa8e2
-  data.tar.gz: f2482b7a54d099c9760b59411936913f8891a8b4
+SHA256:
+  metadata.gz: 8e73fd657e1a344d3cb67b5bf01cd33f8e227447e92e6e93b575a51a0091a253
+  data.tar.gz: c9f41ad884326c341d9c25746bfb80967206c5d0f94ef2bf94a4de6dd7e74435
 SHA512:
-  metadata.gz: e29a4cce1280e602b8d5e285b8d644e925fb84f9cda344dbf60b7c867dff2e0d21065f68e3111813c8d762f9398ac681bd7ae9580fa0519e7a7f81d77a743e6a
-  data.tar.gz: 6a119baa3ad8ca41b61529696d011d8d6ee9466ef4e519701c22bc81e901e91f0d98d460de0cab6040bfbeae42f48d0d9ea77d952594a316b77faeafa7faf8e2
+  metadata.gz: 4aa2e43dbde3b105b5f85c74ac84a4269cd67d2de6b327cc597854ef1e6e4d66ce52628e9564785a0f1729527e90514e2577c83a651d8fe6c82c765c73a8ecbc
+  data.tar.gz: 50df29f0e9ad79c5dd7586dd1190585badb8ae3e09b82847433721cded33a6aa562ccba34be65c12356ca00cde64a45a18bf9dde1592af614a52263d71bca2f4

data/README.md

@@ -26,9 +26,14 @@ TODO: Write usage instructions here
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake rake` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version,
+push git commits and tags and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/grafana/admin.rb

@@ -62,47 +62,36 @@ module Grafana
       user_name   = validate( params, required: true, var: 'user_name', type: String )
       permissions = validate( params, required: true, var: 'permissions' )
       raise ArgumentError.new(format('wrong type. \'permissions\' must be an String or Hash, given %s', permissions.class.to_s ) ) unless( permissions.is_a?(String) || permissions.is_a?(Hash) )
+      valid_roles    = ['Viewer', 'Editor', 'Read Only Editor', 'Admin']
 
-      valid_perms = ['Viewer','Editor','Read Only Editor','Admin']
+      downcased = Set.new valid_roles.map(&:downcase)
 
-      if( permissions.is_a?( String ) && !valid_perms.include?(permissions) )
-
-        message = format( 'user permissions must be one of %s, given \'%s\'', valid_perms.join(', '), permissions )
-#        logger.warn( message )
-
-        return {
-          'status' => 404,
-          'name' => user_name,
-          'permissions' => permissions,
-          'message' => message
-        }
-
-      elsif( permissions.is_a?(Hash) && !permissions.dig(:grafana_admin).nil? )
+      if( permissions.is_a?(String) )
+        unless( downcased.include?( permissions.downcase ) )
+          return {
+            'status' => 404,
+            'name' => user_name,
+            'permissions' => permissions,
+            'message' => format( 'wrong permissions. Must be one of %s, given \'%s\'', valid_roles.join(', '), permissions )
+          }
+        end
+      end
 
+      if( permissions.is_a?(Hash) && !permissions.dig(:grafana_admin).nil? )
         grafana_admin = permissions.dig(:grafana_admin)
-
         unless( grafana_admin.is_a?(Boolean) )
-
-          message = 'Grafana admin permission must be either \'true\' or \'false\''
-#           logger.warn( message )
-
           return {
             'status' => 404,
             'name' => user_name,
             'permissions' => permissions,
-            'message' => message
+            'message' => 'Grafana admin permission must be either \'true\' or \'false\''
           }
         end
       end
 
-      usr = user_by_name(user_name)
+      usr = user(user_name)
 
-      if( usr.nil? || usr.dig('status').to_i != 200 )
-        return {
-          'status' => 404,
-          'message' => format('User \'%s\' not found', user_name)
-        }
-      end
+      return { 'status' => 404, 'message' => format('User \'%s\' not found', user_name) } if( usr.nil? || usr.dig('status').to_i != 200 )
 
       user_id = usr.dig('id')
 
@@ -117,24 +106,25 @@ module Grafana
         logger.debug(payload.to_json) if(@debug)
 
         return put(endpoint, payload.to_json )
-      else
+      end
 
-        org = current_organization
+      org = current_organization
 
-        endpoint = format( '/api/orgs/%s/users/%s', org['id'], user_id )
-        logger.debug( format( 'Updating user id %s permissions', user_id ) ) if @debug
+      return { 'status' => 404, 'message' => 'No current Organization found' } if( org.nil? || org.dig('status').to_i != 200 )
 
-        payload = {
-          name: org.dig('name'),
-          orgId: org.dig('id'),
-          role: permissions.downcase.capitalize
-        }
+      endpoint = format( '/api/orgs/%s/users/%s', org.dig('id'), user_id )
+      logger.debug( format( 'Updating user id %s permissions', user_id ) ) if @debug
 
-        logger.debug("Updating user id #{user_id} permissions (PATCH #{endpoint})") if @debug
-        logger.debug(payload.to_json) if(@debug)
+      payload = {
+        name: org.dig('name'),
+        orgId: org.dig('id'),
+        role: permissions.downcase.capitalize
+      }
 
-        return patch( endpoint, payload.to_json )
-      end
+      logger.debug("Updating user id #{user_id} permissions (PATCH #{endpoint})") if @debug
+      logger.debug(payload.to_json) if(@debug)
+
+      patch( endpoint, payload.to_json )
     end
 
     # Delete an Global User
@@ -152,27 +142,17 @@ module Grafana
     #
     def delete_user( user_id )
 
-      raise ArgumentError.new(format('wrong type. user \'user_id\' must be an String (for an User name) or an Integer (for an User Id), given \'%s\'', user_id.class.to_s)) if( user_id.is_a?(String) && user_id.is_a?(Integer) )
+      raise ArgumentError.new(format('wrong type. user \'user_id\' must be an String (for an User name) or an Integer (for an User Id), given \'%s\'', user_id.class.to_s))  \
+        if( user_id.is_a?(String) && user_id.is_a?(Integer) )
       raise ArgumentError.new('missing \'user_id\'') if( user_id.size.zero? )
 
       if(user_id.is_a?(String))
-        usr = user_by_name(user_id)
+        usr = user(user_id)
         user_id = usr.dig('id')
       end
 
-      if( user_id.nil? )
-        return {
-          'status' => 404,
-          'message' => format( 'No User \'%s\' found', user_id)
-        }
-      end
-
-      if( user_id.is_a?(Integer) && user_id.to_i.zero? )
-        return {
-          'status' => 403,
-          'message' => format( 'Can\'t delete user id %d (admin user)', user_id )
-        }
-      end
+      return { 'status' => 404, 'message' => format( 'No User \'%s\' found', user_id) } if( user_id.nil? )
+      return { 'status' => 403, 'message' => format( 'Can\'t delete user id %d (admin user)', user_id ) } if( user_id.is_a?(Integer) && user_id.to_i.zero? )
 
       endpoint = format('/api/admin/users/%d', user_id )
       logger.debug( "Deleting user id #{user_id} (DELETE #{endpoint})" ) if @debug
@@ -210,7 +190,7 @@ module Grafana
       login_name = validate( params, required: false, var: 'login_name', type: String ) || user_name
       password = validate( params, required: true, var: 'password', type: String )
 
-      usr = user_by_name(user_name)
+      usr = user(user_name)
 
       if( usr.nil? || usr.dig('status').to_i == 200 )
         return {
@@ -239,7 +219,6 @@ module Grafana
       post( endpoint, payload.to_json)
     end
 
-
     # Change Password for User
     #
     # Only works with Basic Authentication (username and password).
@@ -264,16 +243,11 @@ module Grafana
       raise ArgumentError.new('missing params') if( params.size.zero? )
 
       user_name = validate( params, required: true, var: 'user_name', type: String )
-      password = validate( params, required: true, var: 'password', type: String )
+      password  = validate( params, required: true, var: 'password', type: String )
 
-      usr = user_by_name(user_name)
+      usr = user(user_name)
 
-      if( usr.nil? || usr.dig('status').to_i != 200 )
-        return {
-          'status' => 404,
-          'message' => format('User \'%s\' not found', user_name)
-        }
-      end
+      return { 'status' => 404, 'message' => format('User \'%s\' not found', user_name) } if( usr.nil? || usr.dig('status').to_i != 200 )
 
       user_id = usr.dig('id')
 

data/lib/grafana/alerts.rb

@@ -1,38 +1,358 @@
 
 module Grafana
 
-  # http://docs.grafana.org/http_api/alerting/
+  # You can use the Alerting API to get information about alerts and their states but this API cannot be used to modify the alert.
+  # To create new alerts or modify them you need to update the dashboard json that contains the alerts.
+  #
+  # This API can also be used to create, update and delete alert notifications.
+  #
+  # original API Documentation can be found under: http://docs.grafana.org/http_api/alerting/
   #
   module Alerts
 
     # Get alerts
+    #
+    # These parameters are used as querystring parameters. For example:
+    #
+    # @param [Hash] params
+    # @option params [Mixed] dashboard_id alerts for a specified dashboard.
+    # @option params [Integer] panel_id alerts for a specified panel on a dashboard.
+    # @option params [Integer] limit (10) response to x number of alerts.
+    # @option params [Integer] state (ALL,no_data, paused, alerting, ok, pending)
+    # @option params [Array] alerts with one or more of the following alert states: 'ALL', 'no_data', 'paused', 'alerting', 'ok', 'pending'.
+    ## To specify multiple states use the following format: ?state=paused&state=alerting
+    #
+    # @return [Array]
     # GET /api/alerts/
+    # curl -H 'Content-Type: application/json;charset=UTF-8' 'http://admin:admin@127.0.0.1:3030/api/alerts'
     #
+    def alerts( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+#       raise ArgumentError.new('missing \'params\'') if( params.size.zero? )
+
+      dashboard_id = validate( params, required: false, var: 'dashboard_id' )
+      panel_id     = validate( params, required: false, var: 'panel_id', type: Integer )
+      limit        = validate( params, required: false, var: 'limit', type: Integer )
+      alert_array  = validate( params, required: false, var: 'alerts', type: Array )
+      valid_alerts = %w[ALL no_data paused alerting ok pending].sort
+
+      unless( alert_array.nil? )
+        alert_array  = alert_array.sort
+#         valid   = alert_array & valid_alerts
+        invalid = alert_array - valid_alerts
+
+        raise ArgumentError.new(format('wrong alerts type. only %s allowed, given \'%s\'', valid_alerts.join(', '), alert_array.join(', '))) if( invalid.count != 0 )
+      end
+
+      if( dashboard_id.is_a?(String) )
+
+        dashboard = search_dashboards( query: dashboard_id )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard_id) } if( dashboard.nil? || dashboard.dig('status').to_i != 200 )
+
+        dashboard = dashboard.dig('message').first unless( dashboard.nil? && dashboard.dig('status').to_i == 200 )
+        dashboard_id = dashboard.dig('id') unless( dashboard.nil? )
+
+        return { 'status' => 404, 'message' => format( 'No Dashboard \'%s\' found', dashboard_id) } if( dashboard_id.nil? )
+      end
+
+      api     = []
+      api << format( 'dashboardId=%s', dashboard_id ) unless( dashboard_id.nil? )
+      api << format( 'panelId=%s', panel_id ) unless( panel_id.nil? )
+      api << format( 'limit=%s', limit ) unless( limit.nil? )
+
+      unless( alert_array.nil? )
+        alert_array = alert_array.join( '&state=' ) if( alert_array.is_a?( Array ) )
+        api << format( 'state=%s', alert_array )
+      end
+      api = api.join( '&' )
+
+      endpoint = format( '/api/alerts/?%s' , api )
+
+      @logger.debug("Attempting to search for alerts (GET #{endpoint})") if @debug
+
+      get( endpoint )
+    end
+
     # Get one alert
-    # GET /api/alerts/:id
     #
-    def alerts( id = nil ); end
+    # @param [Mixed] alert_id Alertname (String) or Alertid (Integer)
+    #
+    # @example
+    #    alert( 1 )
+    #    alert( 'foo' )
+    #
+    # @return [Hash]
+    #
+    # curl -H 'Content-Type: application/json;charset=UTF-8' 'http://admin:admin@127.0.0.1:3030/api/alerts/1'
+    #
+    def alert( alert_id )
 
-    # Pause alert
-    # POST /api/alerts/:id/pause
-    def alert_pause( id ); end
+      if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )
+
+#       if(alert_id.is_a?(String))
+#         data = alerts( alerts: 'all' ).select { |_k,v| v['name'] == alert_id }
+#         alert_id = data.keys.first if( data )
+#       end
+
+#       puts alert_id
+      # GET /api/alerts/:id
+
+
+      endpoint = format( '/api/alerts/%d' , alert_id )
+
+#       puts endpoint
+
+      @logger.debug("Attempting get alert id #{alert_id} (GET #{endpoint})") if @debug
+
+      get( endpoint )
+    end
+
+
+    # Pause single alert
+    #
+    # @param [Mixed] alert_id Alertname (String) or Alertid (Integer)
+    #
+    # @example
+    #    alert_pause( 1 )
+    #    alert_pause( 'foo' )
+    #
+    # @return [Hash]
+    #
+    def alert_pause( alert_id )
+
+      if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )
+
+      if(alert_id.is_a?(String))
+        data = alerts( alerts: 'all' ).select { |_k,v| v['name'] == alert_id }
+        alert_id = data.keys.first if( data )
+      end
+
+      # POST /api/alerts/:id/pause
+#       puts alert_id
+    end
 
     # Get alert notifications
-    # GET /api/alert-notifications
-    def alert_notifications; end
+    #
+    # @example
+    #    alert_notifications
+    #
+    # @return [Hash]
+    #
+    def alert_notifications
+      logger.debug('Getting alert notifications') if @debug
+      get('/api/alert-notifications')
+    end
+
+
+
+
+
 
     # Create alert notification
-    # POST /api/alert-notifications
-    def create_alert_notification( oarams ); end
+    #
+    # @param [Hash] params
+    # @option params [String] name short description - required
+    # @option params [String] type one of 'slack', 'pagerduty','email','webhook','kafka','hipchat',
+    #                               'victorops','sensu','opsgenie','threema','pushover','telegram','line','prometheus-alertmanager' - required
+    # @option params [Boolean] default (false)
+    # @option params [Hash] settings
+    #
+    # @example
+    #    params = {
+    #      name: 'new alert notification',
+    #      type:  'email',
+    #      default: false,
+    #      settings: {
+    #        addresses: 'carl@grafana.com;dev@grafana.com'
+    #      }
+    #    }
+    #    create_alert_notification( params )
+    #
+    # @return [Hash]
+    #
+    def create_alert_notification( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing params') if( params.size.zero? )
+
+      # TODO
+      # type are 'email'
+      # and the other possible values?
+      name     = validate( params, required: true, var: 'name', type: String )
+      type     = validate( params, required: true, var: 'type', type: String ) || 'email'
+      default  = validate( params, required: false, var: 'default', type: Boolean ) || false
+      settings = validate( params, required: false, var: 'settings', type: Hash )
+
+      unless( type.nil? )
+        valid_types = %w[slack pagerduty email webhook kafka hipchat victorops sensu opsgenie threema pushover telegram line prometheus-alertmanager]
+        raise ArgumentError.new(format('wrong notification type. only %s allowed, given \%s\'', valid_types.join(', '), type)) if( valid_types.include?(type.downcase) == false )
+      end
+
+      # TODO
+      # check if the alert 'name' already created
+      return { 'status' => 404, 'message' => format( 'alert notification \'%s\' alread exists', name) } if( alert_notification?(name) )
+
+#       data = alert_notifications
+#       data = data.dig('message').first unless( data.nil? && data.dig('status').to_i == 200 )
+#       data = data.select { |k| k['name'] == name }
+#       return { 'status' => 404, 'message' => format( 'alert notification \'%s\' alread exists', name) } if( data )
+
+      payload = {
+        name: name,
+        type: type,
+        isDefault: default,
+        settings: settings
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      endpoint = '/api/alert-notifications'
+
+#       puts endpoint
+#       puts payload
+
+      post(endpoint, payload.to_json)
+    end
 
     # Update alert notification
-    # PUT /api/alert-notifications/1
-    def update_alert_notification( params ); end
+    #
+    # @param [Hash] params
+    # @param [Mixed] alert_id Alertname (String) or Alertid (Integer) to change
+    # @option params [String] name short description - required
+    # @option params [String] type ('email') - required
+    # @option params [Boolean] default (false)
+    # @option params [Hash] settings
+    #
+    # @example
+    #    params = {
+    #      alert_id: 1
+    #      name: 'new alert notification',
+    #      type:  'email',
+    #      default: false,
+    #      settings: {
+    #        addresses: 'carl@grafana.com;dev@grafana.com'
+    #      }
+    #    }
+    #    update_alert_notification( params )
+    #
+    #    params = {
+    #      alert_id: 'new alert notification'
+    #      name: 'new alert notification',
+    #      type:  'email',
+    #      default: false,
+    #      settings: {
+    #       addresses: 'carl@grafana.com;dev@grafana.com'
+    #      }
+    #    }
+    #    update_alert_notification( params )
+    #
+    # @return [Hash]
+    #
+    def update_alert_notification( params )
+
+      raise ArgumentError.new(format('wrong type. \'params\' must be an Hash, given \'%s\'', params.class.to_s)) unless( params.is_a?(Hash) )
+      raise ArgumentError.new('missing params') if( params.size.zero? )
+
+      # TODO
+      # type are 'email'
+      # and the other possible values?
+      alert_id = validate( params, required: true, var: 'alert_id' )
+      name     = validate( params, required: true, var: 'name', type: String )
+      type     = validate( params, required: true, var: 'type', type: String ) || 'email'
+      default  = validate( params, required: false, var: 'default', type: Boolean ) || false
+      settings = validate( params, required: false, var: 'settings', type: Hash )
+
+      unless( type.nil? )
+        valid_types = %w[slack pagerduty email webhook kafka hipchat victorops sensu opsgenie threema pushover telegram line prometheus-alertmanager]
+        raise ArgumentError.new(format('wrong notification type. only %s allowed, given \%s\'', valid_types.join(', '), type)) if( valid_types.include?(type.downcase) == false )
+      end
+
+      if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. user \'alert_id\' must be an String (for an Alertname) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
+      end
+
+      alert_id = alert_notification_id(alert_id)
+      return { 'status' => 404, 'message' => format( 'alert notification \'%s\' not exists', name) } if( alert_id.nil? )
+
+      payload = {
+        id: alert_id,
+        name: name,
+        type: type,
+        isDefault: default,
+        settings: settings
+      }
+      payload.reject!{ |_k, v| v.nil? }
+
+      endpoint = format( '/api/alert-notifications/%d', alert_id )
+
+      put(endpoint, payload.to_json)
+    end
 
     # Delete alert notification
-    # DELETE /api/alert-notifications/:notificationId
-    def delete_alert_notification( id ); end
+    #
+    # @param [Mixed] alert_id Alertname (String) or Alertid (Integer)
+    #
+    # @example
+    #    delete_alert_notification( 1 )
+    #    delete_alert_notification( 'foo' )
+    #
+    # @return [Hash]
+    #
+    def delete_alert_notification( alert_id )
+
+      if( alert_id.is_a?(String) && alert_id.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. user \'alert_id\' must be an String (for an Alert name) or an Integer (for an Alert Id), given \'%s\'', alert_id.class.to_s))
+      end
+      raise ArgumentError.new('missing \'alert_id\'') if( alert_id.size.zero? )
+
+      id = alert_notification_id(alert_id)
+      return { 'status' => 404, 'message' => format( 'alert notification \'%s\' not exists', alert_id) } if( id.nil? )
+
+      endpoint = format('/api/alert-notifications/%d', alert_id )
+      logger.debug( "Deleting alert id #{alert_id} (DELETE #{endpoint})" ) if @debug
+
+      delete( endpoint )
+    end
+
+
+    private
+    def alert_notification?( alert_id )
+
+      id = alert_notification_id(alert_id)
+
+      return true unless( id.nil? )
+
+      false
+    end
+
+    def alert_notification_id( alert_id )
+
+      data = alert_notifications
+      data = data.dig('message') unless( data.nil? && data.dig('status').to_i == 200 )
+
+      map = {}
+      data.each do |d|
+        map[d.dig('id')] = d.dig('name').downcase.split.join('_')
+      end
+
+      id = map.select { |key,_value| key == alert_id } if( map && alert_id.is_a?(Integer) )
+      id = map.select { |_key,value| value == alert_id.downcase.split.join('_') } if( map && alert_id.is_a?(String) )
+
+      id = id.keys.first unless(id.nil?)
+
+      return id if( id.is_a?(Integer) )
+
+      nil
+    end
 
   end
 
 end
+