Managing archiving by using the API

Prerequisites on the IBM Log Analysis service

• You must have a paid service plan for the IBM Log Analysis service. Learn more.

• Check that your user ID has permissions to manage archiving. The following table lists the minimum roles that a user must have to manage archiving by using the API:

For more information on how to configure policies for a user, see Granting user permissions to a user or service ID.

You must have a COS bucket configured, and the details of the service credential that you must use to write data to the bucket. For more information on creating buckets, see Create some buckets to store your data.

Get details of the archiving configuration

Use this method to get the details about an existing streaming configuration.

curl -X GET https://<ENDPOINT>/v1/config/archiving
 -H "content-type: application/json"
 -H "servicekey: <SERVICE_KEY>"

• Replace <ENDPOINT> with the IBM Log Analysis API endpoint. To see the list of endpoints, see Endpoints.
• Replace the <SERVICE_KEY> with a valid service key for the IBM Log Analysis instance where you plan to configure archiving. For more information, see Service keys by using the API.

For example, the following is a sample get request:

curl -X GET https://api.us-south.logging.cloud.ibm.com/v1/config/archiving
 -H "content-type: application/json"
 -H "servicekey: xxxxxxxx"

The response will be similar to the following:

{"integration":"ibm","bucket":"my-bucket","endpoint":"s3.private.us-south.cloud-object-storage.appdomain.cloud","apikey":"xxxxxxxxx>","resourceinstanceid":"crn:v1:bluemix:public:cloud-object-storage:global:a/yyyyyyy::"}

Delete the archiving configuration

Use this method to delete an existing archiving configuration.

curl -X DELETE https://<ENDPOINT>/v1/config/archiving
 -H "content-type: application/json"
 -H "servicekey: <SERVICE_KEY>"

• Replace <ENDPOINT> with the IBM Log Analysis API endpoint. To see the list of endpoints, see Endpoints.
• Replace the <SERVICE_KEY> with a valid service key for the IBM Log Analysis instance where you plan to configure archiving. For more information, see Service keys by using the API.

The response will be similar to the following if the configuration is successfully deleted:

{"deleted":true}

If an incorrect service key was specified, a response similar to the following will be returned:

{"error":"Service Key Validation Error: Invalid or deactivated servicekey","status":"error","code":"NotAuthorized"}

Configure archiving

Use this method to create a streaming configuration.

You must have a IBM Cloud Object Storage bucket configured before you configure archiving. If you do not have a bucket configured, you will get an error when trying to use this method.

curl -X POST https://<ENDPOINT>/v1/config/archiving
 -H "content-type: application/json"
 -H "servicekey: <SERVICE_KEY>"
 -d '{"integration": "ibm", "bucket": "<BUCKET>", "endpoint": "<COS_ENDPOINT>", "apikey": "<API_KEY>", "resourceinstanceid": "<ID>"}'

• Replace <ENDPOINT> with the IBM Log Analysis API endpoint. To see the list of endpoints, see Endpoints.
• Replace the <SERVICE_KEY> with a valid service key for the IBM Log Analysis instance where you plan to configure archiving. For more information, see Service keys by using the API.
• Replace <BUCKET> with the name of your IBM Cloud Object Storage bucket.
• Replace <COS_ENDPOINT> with your IBM Cloud Object Storage endpoint associated with the bucket.
• Replace <API_KEY> with the API key required to authenticate with IBM Cloud Object Storage.
• Replace <ID> With the CRN of the IBM Cloud Object Storage instance where the bucket is located.

The response will be similar to the following if the configuration is successfully configured:

{"integration":"ibm","bucket":"my-bucket","endpoint":"s3.private.us-south.cloud-object-storage.appdomain.cloud","apikey":"xxxxxxxxx>","resourceinstanceid":"crn:v1:bluemix:public:cloud-object-storage:global:a/yyyyyyy::"}

Monitor archiving with Activity Tracker and IBM Cloud Monitoring.

Update the archiving configuration

Use this method to update an archiving configuration.

curl -X PUT https://api.eu-gb.logging.cloud.ibm.com/v1/config/archiving
 -H "content-type: application/json"
 -H "servicekey: <SERVICE_KEY>"
 -d '{"integration": "ibm", "bucket": "<BUCKET>", "endpoint": "<COS_ENDPOINT>", "apikey": "<API_KEY>", "resourceinstanceid": "<ID>"}'

• Replace <ENDPOINT> with the IBM Log Analysis API endpoint. To see the list of endpoints, see Endpoints.
• Replace the <SERVICE_KEY> with a valid service key for the IBM Log Analysis instance where you plan to configure archiving. For more information, see Service keys by using the API.
• Replace <BUCKET> with the name of your IBM Cloud Object Storage bucket.
• Replace <COS_ENDPOINT> with your IBM Cloud Object Storage endpoint associated with the bucket.
• Replace <API_KEY> with the API key required to authenticate with IBM Cloud Object Storage.
• Replace <ID> With the CRN of the IBM Cloud Object Storage instance where the bucket is located.

The response will be similar to the following if the configuration is successfully updated:

{"integration":"ibm","bucket":"my-bucket","endpoint":"s3.private.us-south.cloud-object-storage.appdomain.cloud","apikey":"xxxxxxxxx>","resourceinstanceid":"crn:v1:bluemix:public:cloud-object-storage:global:a/yyyyyyy::"}

If archiving is not configured, the following will be returned when trying to do an update:

{"error":"Active archiving configuration does not exist for this account. Try creating one instead.","code":"ServerError","status":"error"}

Check the status of a archiving configuration

To check if archiving is enabled or disabled, you can use either the GET or PUT methods.

When streaming is not enabled, the following is returned when running the GET method:

{"error":"No active archiving configuration exists","code":"NotFound","status":"error"}

When archiving is not enabled, the following is returned when running the PUT method:

{"error":"Active archiving configuration does not exist for this account. Try creating one instead.","code":"ServerError","status":"error"}