grafana 0.8.5 → 1.1.0

data/lib/grafana/client.rb

@@ -5,21 +5,31 @@ require 'rest-client'
 require 'json'
 require 'timeout'
 
+require_relative 'logging'
 require_relative 'version'
+require_relative 'auth'
 require_relative 'validator'
 require_relative 'login'
 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'
+require_relative 'playlist'
 
 # -------------------------------------------------------------------------------------------------------------------
 #
@@ -40,20 +50,29 @@ module Grafana
     include Logging
 
     include Grafana::Version
+    include Grafana::Auth
     include Grafana::Validator
     include Grafana::Login
     include Grafana::Network
     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
+    include Grafana::Playlist
 
     attr_accessor :debug
 
@@ -95,8 +114,17 @@ module Grafana
       ssl                 = settings.dig(:grafana, :ssl)           || false
       @timeout            = settings.dig(:grafana, :timeout)       || 5
       @open_timeout       = settings.dig(:grafana, :open_timeout)  || 5
-      @http_headers       = settings.dig(:grafana, :http_headers)  || {}
+      @api_user           = settings.dig(:grafana, :api, :user)    || 'admin'
+      @api_password       = settings.dig(:grafana, :api, :password)
+      @http_headers       = settings.dig(:grafana, :http_headers)  || { 'Content-Type' => 'application/json', 'Accept' => 'application/json' }
       @debug              = settings.dig(:debug)                   || false
+      @debug = false
+      @headers            = {}
+
+      # Token Support for Grafana 6
+      @api_key            = nil
+      @api_token_name     = settings.dig(:grafana, :api, :token, :name ) || (0..10).to_a.map{|_a| rand(16).to_s(16)}.join
+      @api_token_lifetime = settings.dig(:grafana, :api, :token, :lifetime ) || 0
 
       raise ArgumentError.new('missing \'host\'') if( host.nil? )
 
@@ -111,14 +139,62 @@ module Grafana
       @url      = format( '%s://%s:%d%s', protocoll, host, port, url_path )
     end
 
-    def self.logger
-      @@logger ||= defined?(Logging) ? Logging.logger : Logger.new(STDOUT)
+
+    def create_instance
+
+      logger.debug( "create_instance" )
+      logger.debug( "@api_key: #{@api_key} #{@api_key.class}" )
+
+      params = { timeout: @timeout.to_i, open_timeout: @open_timeout.to_i, headers: @http_headers, verify_ssl: false }
+      params = { timeout: @timeout.to_i, open_timeout: @open_timeout.to_i, headers: @http_headers, verify_ssl: false, user: @api_user, password: @api_password } if( @api_key.nil? )
+
+      logger.debug( "url   : #{@url}" )
+      logger.debug( "params: #{params}" )
+
+      begin
+        RestClient::Resource.new( @url, params )
+      rescue => error
+        logger.error( error ) # if @debug
+        logger.debug( e.backtrace.join("\n") ) #if @debug
+        false
+      end
     end
 
-    def self.logger=(logger)
-      @@logger = logger
+
+    # 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
+
+      status = s.dig('status')
+      if( status.to_i == 200 )
+        @version =  s.dig('buildInfo','version')
+        @major_version = @version.split('.').first.to_i
+
+        { version: @version, major_version: @major_version }
+      else
+        s
+      end
+    end
+
+
+#    def self.logger
+#      @@logger ||= defined?(Logging) ? Logging.logger : Logger.new(STDOUT)
+#    end
+#
+#    def self.logger=(logger)
+#      @@logger = logger
+#    end
+
   end
 
 end

data/lib/grafana/dashboard.rb

@@ -2,12 +2,36 @@
 module Grafana
 
   # http://docs.grafana.org/http_api/dashboard/
+
+  # The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
+  #
+  # The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
+  # It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URL's for
+  # accessing dashboards and when syncing dashboards between multiple Grafana installs, see dashboard provisioning for
+  # more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
+  #
+  # The uid can have a maximum length of 40 characters.
+  #
+  # Deprecated resources
+  #  Please note that these resource have been deprecated and will be removed in a future release.
+  #
+  #  - Get dashboard by slug
+  #  - Delete dashboard by slug
+  #
+  #
   #
   module Dashboard
 
-
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Get dashboard
     #
+    # Will return the dashboard given the dashboard slug.
+    # Slug is the url friendly version of the dashboard title.
+    # If there exists multiple dashboards with the same slug, one of them will be returned in the response.
+    #
     # @example
     #    dashboard('dashboard for many foo')
     #
@@ -18,23 +42,70 @@ module Grafana
       raise ArgumentError.new(format('wrong type. \'name\' must be an String, given \'%s\'', name.class.to_s)) unless( name.is_a?(String) )
       raise ArgumentError.new('missing name') if( name.size.zero? )
 
+#       v, mv = version.values
+#
+#       if( mv == 5)
+#         puts 'DEPRICATION WARNING'
+#         puts 'Grafana v5.0 use a new interal id/uid handling'
+#         puts 'This function works well with Grafana v4.x'
+#       end
+
       endpoint = format( '/api/dashboards/db/%s', slug(name) )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
+
+      get( endpoint )
+    end
+
+    # http://docs.grafana.org/http_api/dashboard/#get-dashboard-by-uid
+    #
+    # GET /api/dashboards/uid/:uid
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # Get dashboard
+    #
+    # Will return the dashboard given the dashboard unique identifier (uid).
+    #
+    # @example
+    #    dashboard('L42r6NWiz')
+    #
+    # @return [String]
+    #
+    def dashboard_by_uid( uid )
+
+      if( uid.is_a?(String) && uid.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. dashboard \'uid\' must be an String (for an title name) or an Integer (for an Datasource Id), given \'%s\'', uid.class.to_s))
+      end
+      raise ArgumentError.new('missing \'uid\'') if( uid.size.zero? )
 
-      @logger.debug( "Attempting to get dashboard (GET /api/dashboards/db/#{name})" ) if @debug
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'uid has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      return { 'status' => 404, 'message' => format( 'The uid can have a maximum length of 40 characters, but it is %s characters long', uid.length) } if( uid.length > 40 )
+
+      endpoint = format( '/api/dashboards/uid/%s', uid )
+      @logger.debug( "Attempting to get dashboard (GET #{endpoint})" ) if @debug
 
       get( endpoint )
     end
 
     # Create / Update dashboard
     #
+    # Creates a new dashboard or updates an existing dashboard.
+    #
     # @param [Hash] params
-    # @option params [Hash] dashboard
+    # @option params [Hash] dashboard The complete dashboard model
+    #  - dashboard.id - id = null to create a new dashboard.
+    #  - dashboard.uid - Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
+    #  - folderId - The id of the folder to save the dashboard in.
+    #  - overwrite - Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
+    #  - message - Set a commit message for the version history.
     # @option params [Boolean] overwrite (true)
     #
     # @example
     #    params = {
     #      dashboard: {
     #        id: null,
+    #        uid: null,
     #        title: 'Production Overview',
     #        tags: [ 'templated' ],
     #        timezone": 'browser',
@@ -45,7 +116,9 @@ module Grafana
     #        'schemaVersion': 6,
     #        'version': 0
     #      },
-    #      overwrite: false
+    #      folderId: 0,
+    #      overwrite: false,
+    #      message: 'created by foo'
     #    }
     #    create_dashboard( params )
     #
@@ -57,19 +130,33 @@ 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? )
 
-      dashboard = validate( params, required: true, var: 'dashboard', type: Hash )
+      dashboard = validate( params, required: true , var: 'dashboard', type: Hash )
       overwrite = validate( params, required: false, var: 'overwrite', type: Boolean ) || true
+      folder_id = validate( params, required: false, var: 'folderId' )
+      message   = validate( params, required: false, var: 'message', type: String )
 
       dashboard = regenerate_template_ids( dashboard )
 
+      unless(folder_id.nil?)
+        f_folder = folder(folder_id)
+        return { 'status' => 404, 'message' => format( 'No Folder \'%s\' found', folder_id) } if( f_folder.dig('status') != 200 )
+
+        folder_id = f_folder.dig('id')
+      end
+
       db = JSON.parse( dashboard ) if( dashboard.is_a?(String) )
       title = db.dig('dashboard','title')
+      uid   = db.dig('dashboard','uid')
+
+      return { 'status' => 404, 'message' => format( 'The template \'%s\' can\'t be create. The uid can have a maximum length of 40 characters, but it is %s characters long', title, uid.length) } if( ! uid.nil? && uid.length > 40 )
 
       endpoint = '/api/dashboards/db'
 
       payload = {
         dashboard: db.dig('dashboard'),
-        overwrite: overwrite
+        overwrite: overwrite,
+        folderId: folder_id,
+        message: message
       }
       payload.reject!{ |_k, v| v.nil? }
 
@@ -78,7 +165,12 @@ module Grafana
       post( endpoint, payload.to_json )
     end
 
+    # http://docs.grafana.org/http_api/dashboard/#delete-dashboard-by-slug
+    #  - Deprecated starting from Grafana v5.0.
+    #    Please update to use the new Get dashboard by uid resource instead
+    #
     # Delete dashboard
+    # Will delete the dashboard given the specified slug. Slug is the url friendly version of the dashboard title.
     #
     # @example
     #    delete_dashboard('dashboard for many foo')
@@ -149,7 +241,7 @@ module Grafana
       tags    = validate( params, required: false, var: 'tags' )
 
       api     = []
-      api << format( 'query=%s', CGI.escape( query ) ) unless  query.nil?
+      api << format( 'query=%s', CGI.escape( query ) ) unless( query.nil? )
       api << format( 'starred=%s', starred ? 'true' : 'false' ) unless( starred.nil? )
 
       unless( tags.nil? )

data/lib/grafana/dashboard_permissions.rb

@@ -0,0 +1,132 @@
+
+module Grafana
+
+  # http://docs.grafana.org/http_api/dashboard_permissions/#dashboard-permissions-api
+  #
+  # This API can be used to update/get the permissions for a dashboard.
+  # Permissions with dashboardId=-1 are the default permissions for users with the Viewer and Editor roles.
+  # Permissions can be set for a user, a team or a role (Viewer or Editor).
+  # Permissions cannot be set for Admins - they always have access to everything.
+  #
+  # The permission levels for the permission field:
+  #
+  #  1 = View
+  #  2 = Edit
+  #  4 = Admin
+  #
+  module DashboardPermissions
+
+    # http://docs.grafana.org/http_api/dashboard_permissions/#get-permissions-for-a-dashboard
+    #
+    # GET /api/dashboards/id/:dashboardId/permissions
+    #
+    # Gets all existing permissions for the dashboard with the given dashboardId.
+    #
+    def dashboard_permissions(uid)
+
+      if( uid.is_a?(String) && uid.is_a?(Integer) )
+        raise ArgumentError.new(format('wrong type. dashboard \'uid\' must be an String (for an title name) or an Integer (for an Datasource Id), given \'%s\'', uid.class.to_s))
+      end
+      raise ArgumentError.new('missing \'uid\'') if( uid.size.zero? )
+
+      endpoint = format( '/api/dashboards/id/%s/permissions', uid )
+      @logger.debug( "Attempting to get dashboard permissions (GET #{endpoint})" ) if @debug
+
+      r = get( endpoint )
+      r['message'] = format('dashboard \'%s\' not found', uid) if(r.dig('status') == 404)
+      r
+    end
+
+    # http://docs.grafana.org/http_api/dashboard_permissions/#update-permissions-for-a-dashboard
+    #
+    # POST /api/dashboards/id/:dashboardId/permissions
+    #
+    # Updates permissions for a dashboard.
+    # This operation will remove existing permissions if they're not included in the request.
+    #
+    #
+    def update_dashboad_permissions(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? )
+
+      v, mv = version.values
+      return { 'status' => 404, 'message' => format( 'folder has been supported in Grafana since version 5. you use version %s', v) } if(mv < 5)
+
+      dashboard_id = validate( params, required: true, var: 'dashboard_id', type: Integer )
+      permissions  = validate( params, required: true, var: 'permissions' , type: Hash )
+
+      return { 'status' => 404, 'message' => 'no permissions given' } if( permissions.size.zero? )
+
+      valid_roles = %w[View Edit Admin]
+
+      c_team = permissions.dig('team')
+      c_user = permissions.dig('user')
+      team   = []
+      user   = []
+
+      unless(c_team.nil?)
+        check_keys = []
+
+        c_team.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_team = team(k)
+          team_id = f_team.dig('id')
+
+          next unless(( f_team.dig('status') == 200) && !check_keys.include?(team_id) && r == true )
+
+          check_keys << team_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          team << {
+            teamId: team_id,
+            permission: role_id
+          }
+        end
+      end
+
+      unless(c_user.nil?)
+        check_keys = []
+
+        c_user.uniq.each do |x|
+          k = x.keys.first
+          v = x.values.first
+          r = validate_hash( v, valid_roles )
+
+          f_user = user(k)
+          user_id = f_user.dig('id')
+
+          next unless(( f_user.dig('status') == 200) && !check_keys.include?(user_id) && r == true )
+
+          check_keys << user_id
+
+          role_id = valid_roles.index(v)
+          role_id += 1
+          role_id += 1 if(v == 'Admin')
+
+          user << {
+            userId: user_id,
+            permission: role_id
+          }
+        end
+      end
+
+      payload = {
+        items: team + user
+      }
+      payload.reject!{ |_, y| y.nil? }
+
+
+      endpoint = format('/api/dashboards/id/%s/permissions', dashboard_id)
+      post(endpoint, payload.to_json)
+    end
+
+  end
+
+end