IBM Cloud Docs
Using the Python client

Using the Python client

You can use the Python Client to manage the IBM Cloud Monitoring service. The client is also known as the sdcclient.

These instructions apply to Python version 3.x.

To manage resources that are associated with the default team, use IAM as your authentication method.

To manage resources that are associated with a team, you must use the Monitoring API token that is active for the team.

Step 1. Installing the Python client

Prerequisites

Install the following Python packages that you need when you use Python version 3 or later:

  1. Run the following command to install the request package:

    pip3 install requests

  2. Run the following command to install the pyyaml package:

    python3 -m pip install pyyaml

Installing the Python client by using pip

From a terminal, run the following comnmnand:

The sddclient version must be at least 0.9.x.

# sddclient version must be at least 0.9.0
pip3 install sdcclient

Installing the Python client from a GitHub repo

Complete the following steps:

  1. Make a folder to copy the client code.

    mkdir python-client && cd python-client

  2. Clone the repository.

    git clone https://github.com/draios/python-sdc-client.git

  3. Create an empty Python script.

    touch script.py

  4. Confirm python-sdc-client/script.py is listed when you verify the contents of the folder python-client.

    ls

Step 2. Reference the Python client in your Python script

Reference the Python client that is installed by using pip

You can reference the Python client by adding the following statement to your Python script:

from sdcclient import IbmAuthHelper, SdMonitorClient

Reference the Python client that is installed by cloning a GitHub repo

Add the following entries to your Python script to import the GitHub cloned package into your script:

import sys
sys.path.append("python-sdc-client")
from sdcclient import IbmAuthHelper, SdMonitorClient

Step 3. Instantiate the Monitoring Python client

Option 1. Authenticate your user or service ID by using IAM

To use IBM Cloud IAM authentication with the Python client, you must specify a Monitoring endpoint, an API key, and the GUID from your IBM Cloud Monitoring instance.

Complete the following steps from a terminal:

  1. Get the GUID of your IBM Cloud Monitoring instance. Run the following command:

    ibmcloud resource service-instance <NAME> --output json | jq -r '.[].guid'

  2. Get the API key. Run the following command to generate a user API key:

    ibmcloud iam api-key-create KEY_NAME

  3. Get the endpoint for the region where the monitoring instance is available.

    To see the list of endpoints that are available, see Monitoring endpoints.

    For example, the endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com

  4. Add the following entries to your Python script:

    from sdcclient import IbmAuthHelper, SdMonitorClient

URL = <MONITORING_ENDPOINT>
# For example: URL = 'https://us-south.monitoring.cloud.ibm.com'

APIKEY = <IAM_APIKEY>

GUID = <GUID>

ibm_headers = IbmAuthHelper.get_headers(URL, APIKEY, GUID)
sdclient = SdMonitorClient(sdc_url=URL, custom_headers=ibm_headers)

    Where

    <MONITORING_ENDPOINT> must be replaced with the endpoint where the monitoring instance is available.

    <IAM_APIKEY> must be replaced with a valid IAM API key. Learn more.

    <GUID> must be replaced with the GUID of the monitoring instance that you obtain in the previous step.

You can now use the sdclient to perform actions that will be authenticated by using IAM.

If you get the error 400 Client Error: Bad Request for url: https://iam.cloud.ibm.com/identity/token, check the API key. The value that you are passing is not valid.

Option 2. Authenticate by using the Monitoring API token

You must specify a Monitoring endpoint, and the Monitoring API token that is associated to the team that you want to manage with the Python client.

Complete the following steps from a terminal:

  1. Get the Monitoring API token.

  2. Get the endpoint for the region where the monitoring instance is available.

    To see the list of endpoints that are available, see Monitoring endpoints.

    For example, the endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com

  3. Add the following entries to your Python script:

    from sdcclient import IbmAuthHelper, SdMonitorClient

URL = <MONITORING_ENDPOINT>
# For example: URL = 'https://us-south.monitoring.cloud.ibm.com'

MONITOR_TOKEN = <MONITOR_TOKEN>
# For example: MONITOR_TOKEN = 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

sdclient = SdMonitorClient(token=MONITOR_TOKEN,sdc_url=URL)

    Where

    <MONITORING_ENDPOINT> must be replaced with the endpoint where the monitoring instance is available.

    <MONITOR_TOKEN> must be replaced with the Monitoring API token.

You can now use the sdclient to perform actions that will be authenticated by using IAM.

Sample 1. Python script that uses IAM API key

#!/usr/bin/env python3

import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), '..'))
from sdcclient import IbmAuthHelper, SdMonitorClient

# Parse arguments.
def usage():
   print('usage: %s <ENDPOINT_URL> <API_KEY> <INSTANCE_GUID>' % sys.argv[0])
   print('ENDPOINT_URL: IBM Cloud endpoint URL (e.g. https://us-south.monitoring.cloud.ibm.com')
   print('API_KEY: IBM Cloud IAM API key. This key is used to retrieve an IAM access token.')
   print('INSTANCE_GUID: GUID of an IBM Cloud Monitoring.')
   sys.exit(1)

if len(sys.argv) != 4:
   usage()

URL = sys.argv[1]
APIKEY = sys.argv[2]
GUID = sys.argv[3]


# Instantiate the client
ibm_headers = IbmAuthHelper.get_headers(URL, APIKEY, GUID)
sdclient = SdMonitorClient(sdc_url=URL, custom_headers=ibm_headers)

Sample 2. Python script that uses a Monitoring API token

#!/usr/bin/env python3

import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), '..'))

from sdcclient import IbmAuthHelper, SdMonitorClient

# Parse arguments.
def usage():
   print('usage: %s <ENDPOINT_URL> <MONITOR_TOKEN> <INSTANCE_GUID>' % sys.argv[0])
   print('ENDPOINT_URL: IBM Cloud endpoint URL (e.g. https://us-south.monitoring.cloud.ibm.com')
   print('MONITOR_TOKEN: token that is associated to a team.')
   sys.exit(1)

if len(sys.argv) != 3:
   usage()

URL = sys.argv[1]
MONITOR_TOKEN = sys.argv[2]

# Instantiate the client
sdclient = SdMonitorClient(token=MONITOR_TOKEN,sdc_url=URL)

References