grafana 0.9.0 → 0.10.1

data/doc/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Wed Dec 13 06:51:14 2017 by
+  Generated on Thu Dec 14 05:45:14 2017 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.11 (ruby-2.2.8).
 </div>

data/lib/grafana/admin.rb

@@ -142,7 +142,8 @@ 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))

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
+

data/lib/grafana/annotations.rb

@@ -20,10 +20,12 @@ module Grafana
     # @option params [Integer] from: epoch datetime in milliseconds. Optional.
     # @option params [Integer] to: epoch datetime in milliseconds. Optional.
     # @option params [Integer] limit: number. Optional - default is 10. Max limit for results returned.
-    # @option params [Integer] alertId: number. Optional. Find annotations for a specified alert.
+    # @option params [Integer] alert_id: number. Optional. Find annotations for a specified alert.
     # @option params [Mixed] dashboard: number. Optional. Find annotations that are scoped to a specific dashboard
     # @option params [Integer] panel_id: number. Optional. Find annotations that are scoped to a specific panel
-    # @option params [Array] tags: string. Optional. Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times e.g.
+    # @option params [Array] tags: Optional. Use this to filter global annotations.
+    #                              Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel.
+    #                              To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g.
     #
     # @example
     #    params = {
@@ -160,7 +162,7 @@ module Grafana
     #
     # Creates an annotation by using Graphite-compatible event format.
     # The when and data fields are optional.
-    # If when is not specified then the current time will be used as annotation’s timestamp.
+    # If when is not specified then the current time will be used as annotation's timestamp.
     # The tags field can also be in prior to Graphite 0.10.0 format (string with multiple tags being separated by a space).
     #
     # http://docs.grafana.org/http_api/annotations/#create-annotation-in-graphite-format
@@ -177,7 +179,7 @@ module Grafana
     #      what: 'spec test graphite annotation',
     #      when: Time.now.to_i,
     #      tags: [ 'spec', 'test' ],
-    #      text: 'test annotation'
+    #      data: 'test annotation'
     #    }
     #    create_annotation_graphite( params )
     #
@@ -188,17 +190,17 @@ module Grafana
       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? )
 
-      what      = validate( params, required: true, var: 'what', type: String )
+      what      = validate( params, required: true , var: 'what', type: String )
       time_when = validate( params, required: false, var: 'when', type: Integer ) || Time.now.to_i
-      tags      = validate( params, required: true, var: 'tags', type: Array )
-      text      = validate( params, required: true, var: 'text', type: String )
+      tags      = validate( params, required: true , var: 'tags', type: Array )
+      data      = validate( params, required: false, var: 'data', type: String )
 
       endpoint = '/api/annotations/graphite'
       payload = {
         what: what,
         when: time_when,
         tags: tags,
-        text: text
+        data: data
       }
       payload.reject!{ |_k, v| v.nil? }
 

data/lib/grafana/client.rb

@@ -12,14 +12,21 @@ require_relative 'network'
 require_relative 'tools'
 require_relative 'admin'
 require_relative 'annotations'
+require_relative 'preferences'
 require_relative 'user'
 require_relative 'users'
+require_relative 'teams'
 require_relative 'datasource'
 require_relative 'organization'
 require_relative 'organizations'
 require_relative 'dashboard'
 require_relative 'dashboard_versions'
+require_relative 'dashboard_permissions'
 require_relative 'snapshot'
+require_relative 'alerts'
+require_relative 'folder'
+require_relative 'folder_permissions'
+require_relative 'folder_and_dashboard_search'
 
 # -------------------------------------------------------------------------------------------------------------------
 #
@@ -46,14 +53,21 @@ module Grafana
     include Grafana::Tools
     include Grafana::Admin
     include Grafana::Annotations
+    include Grafana::Preferences
     include Grafana::User
     include Grafana::Users
+    include Grafana::Teams
     include Grafana::Datasource
     include Grafana::Organization
     include Grafana::Organizations
     include Grafana::Dashboard
     include Grafana::DashboardVersions
+    include Grafana::DashboardPermissions
     include Grafana::Snapshot
+    include Grafana::Alerts
+    include Grafana::Folder
+    include Grafana::FolderPermissions
+    include Grafana::FolderSearch
 
     attr_accessor :debug
 
@@ -98,6 +112,8 @@ module Grafana
       @http_headers       = settings.dig(:grafana, :http_headers)  || {}
       @debug              = settings.dig(:debug)                   || false
 
+      @headers            = {}
+
       raise ArgumentError.new('missing \'host\'') if( host.nil? )
 
       raise ArgumentError.new(format('wrong type. \'port\' must be an Integer, given \'%s\'', port.class.to_s)) unless( port.is_a?(Integer) )
@@ -111,6 +127,26 @@ module Grafana
       @url      = format( '%s://%s:%d%s', protocoll, host, port, url_path )
     end
 
+    # Get Settings
+    #
+    # http://docs.grafana.org/http_api/other/#get-settings
+    #
+    def settings
+      endpoint = '/api/frontend/settings'
+      @logger.debug("Getting all settings (GET #{endpoint})") if @debug
+      get(endpoint)
+    end
+
+
+    def version
+      s = settings
+      @version =  s.dig('buildInfo','version')
+      @major_version = @version.split('.').first.to_i
+
+      {version: @version, major_version: @major_version}
+    end
+
+
     def self.logger
       @@logger ||= defined?(Logging) ? Logging.logger : Logger.new(STDOUT)
     end