Introduction IBM® Cloud Logs is a scalable logging service that persists logs and provides users with capabilities for querying, tailing, and visualizing logs. Go SDK is available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDK implement best practices for using the API and reduce the amount of code that you need to write. The tab for Go includes code examples that demonstrate how to use the client libraries. For more information about using the SDK, see the IBM Cloud SDK Common projecthttps://github.com/IBM/ibm-cloud-sdk-common on GitHub. Installing the Go SDK Go modules recommended: Add the following import in your code, and then run go build or go mod tidy go import "github.com/IBM/logs-go-sdk/logsv0" Go get bash go get -u github.com/IBM/logs-go-sdk View on GitHub https://github.com/IBM/logs-go-sdkhttps://github.com/IBM/logs-go-sdk Endpoint URLs The API endpoint URL is unique per region for an instance of IBM Cloud Logs. For example, when IBM Cloud Logs is hosted in Madrid eu-es, the base URL is https://{instanceID}.api.eu-es.logs.cloud.ibm.com The version information is appended to the base URL to access resources. For example /v1, resulting in the URL https://{instanceID}.api.eu-es.logs.cloud.ibm.com/v1 for Madrid eu-es. Base URL bash https://{instanceID}.api.{region}.logs.cloud.ibm.com Example API request bash curl -X {requestmethod} \ -H "Authorization: Bearer {bearertoken}" \ -H "Accept: application/json" \ --data "{requestbody}" \ "https://{instanceID}.api.{region}.logs.cloud.ibm.com/{methodendpoint}" Replace {bearertoken}, {requestmethod}, {methodendpoint} and optional {requestbody} in this example with the values for your particular API call. Authentication Authorization to the IBM Cloud Logs service REST API is enforced by an IBM Cloud® Identity and Access Management IAM access token. The token is used to determine the actions that a user or service ID has access to when they use the API. Retrieving an access token is supported using an IAM Trusted Profile or IAM API key. To request an access token with a Trusted Profile from within your IBM Cloud Kubernetes Service or Red Hat OpenShift cluster, run the following command: bash curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ --data "granttype=urn:ibm:params:oauth:grant-type:cr-token" \ --data "profileid={trustedprofileid}" \ --data-urlencode "crtoken@{pathtotoken}" \ https://iam.cloud.ibm.com/identity/token Replace {trustedprofileid} and {pathtotoken} with the correct values for your environment. To request an access token with an IAM apikey, run the following command: bash curl -X POST \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data "granttype=urn:ibm:params:oauth:grant-type:apikey" \ --data "apikey=${IAMAPIKEY}" \ "https://iam.cloud.ibm.com/identity/token" Replace {IAMAPIKEY} with your IAM API key. The access token is provided in the returned JSON data in the field .accesstoken. Error handling The IBM Cloud Logs service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates that a parameter validation failed and can occur if required parameters are missing or if any parameter values are invalid. A 401 or 403 response indicates that the incoming request did not contain valid authentication information. A 500 type response indicates an internal server error that is seen in an unexpected error situation. The IBM Cloud Logs REST APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows: json { "errors": { "code": "notauthorized", "message": "The specified token does not have authority to create a tenant." } , "statuscode": 403 } If an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the Reference section describe example errors that might be returned from a failed request. All responses from the Identity Services REST API are in JSON format. The following table shows the potential error codes the API might return. | HTTP Error Code | Description | Recovery | |-----------------|-------------|----------| | 200 | Success | The request was successful. | | 201 | Created | The resource was successfully created. | | 204 | No Content | The request was successful. No response body is provided. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again. | | 403 | Forbidden | The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions. | | 404 | Not Found | The requested resource can't be found. | | 408 | Request Timeout| The connection to the server timed out. Wait a few minutes, then try again. | | 409 | conflict | The requested resource conflicts with an already existing resource. | | 415 | Bad Request | Missing or wrong header | | 429 | Rate limit exceeded | Reduce the rate of requests or Wait a few minutes, then try again. | | 500 | Internal error | Error that is seen in an unexpected error situation. |
| Method | Path | Summary |
|---|---|---|
| GET | /v1/alert_definitions/{id} | Get an alert definition by ID |
| PUT | /v1/alert_definitions/{id} | Update an alert definition by ID |
| DELETE | /v1/alert_definitions/{id} | Delete an alert definition by ID |
| GET | /v1/alert_definitions | List alert definitions |
| POST | /v1/alert_definitions | Create an alert definition |
| GET | /v1/alerts/{id} | Get an alert by ID |
| PUT | /v1/alerts/{id} | Update an alert |
| DELETE | /v1/alerts/{id} | Delete an alert |
| GET | /v1/alerts | List alerts |
| POST | /v1/alerts | Create an alert |
| POST | /v1/background_query | Submit a background query to be processed asynchronously. |
| GET | /v1/background_query/{query_id}/status | Get the status of a background query |
| GET | /v1/background_query/{query_id}/data | Get the data of a background query |
| POST | /v1/background_query/{query_id}/cancel | Cancel a background query |
| GET | /v1/data_access_rules | Get service instance's Data Access Rules by ids |
| POST | /v1/data_access_rules | Create a data access rule |
| PUT | /v1/data_access_rules/{id} | Update a data access rule |
| DELETE | /v1/data_access_rules/{id} | Delete a data access rule |
| GET | /v1/data_usage | Get data usage metrics export status or return data usage report |
| PUT | /v1/data_usage | Update data usage metrics export status |
| GET | /v1/enrichments | List all enrichments |
| POST | /v1/enrichments | Create an enrichment |
| DELETE | /v1/enrichments/{id} | Delete enrichments |
| GET | /v1/events2metrics | Lists events to metrics definitions |
| POST | /v1/events2metrics | Creates events to metrics definitions |
| GET | /v1/events2metrics/{id} | Gets events to metrics definitions by ID |
| PUT | /v1/events2metrics/{id} | Updates events to metrics definitions |
| DELETE | /v1/events2metrics/{id} | Deletes events to metrics definitions by ID |
| GET | /v1/extensions/{id} | Get an extension by ID |
| GET | /v1/extensions/{id}/deployment | Get deployment details of an extension |
| PUT | /v1/extensions/{id}/deployment | Deploy or update deployment of an extension. |
| DELETE | /v1/extensions/{id}/deployment | Delete deployment of an extension |
| GET | /v1/extensions | Get list of extensions |
| GET | /v1/view_folders | List view's folders |
| POST | /v1/view_folders | Create view folder |
| GET | /v1/view_folders/{id} | Get view folder |
| PUT | /v1/view_folders/{id} | Replaces an existing view folder |
| DELETE | /v1/view_folders/{id} | Deletes a view folder by ID |
| GET | /v1/log_data_retention_tags | Get log data retention tags |
| PUT | /v1/log_data_retention_tags | Update log data retention tags |
| GET | /v1/outgoing_webhooks | List Outbound Integrations. |
| POST | /v1/outgoing_webhooks | Create an outbound integration. |
| GET | /v1/outgoing_webhooks/{id} | Gets an outbound integration by ID. |
| PUT | /v1/outgoing_webhooks/{id} | Update an outbound integration. |
| DELETE | /v1/outgoing_webhooks/{id} | Delete an outbound integration. |
| GET | /v1/policies/{id} | Gets policy by ID |
| PUT | /v1/policies/{id} | Updates an existing policy |
| DELETE | /v1/policies/{id} | Deletes an existing policy |
| GET | /v1/policies | Gets policies |
| POST | /v1/policies | Creates a new policy |
| POST | /v1/query | Run a query to search the logs |
| GET | /v1/rule_groups/{group_id} | Gets rule group by groupid |
| PUT | /v1/rule_groups/{group_id} | Updates rule group by groupid |
| DELETE | /v1/rule_groups/{group_id} | Deletes rule group by groupid |
| GET | /v1/rule_groups | Gets all rule groups |
| POST | /v1/rule_groups | Creates rule group |
| GET | /v1/streams | List all Event Streams. |
| POST | /v1/streams | Create an Event Stream Integration. |
| PUT | /v1/streams/{id} | Update an Event Stream. |
| DELETE | /v1/streams/{id} | Delete an Event Stream integration by ID. |
| GET | /v1/views | Lists all company public views |
| POST | /v1/views | Creates a new view |
| GET | /v1/views/{id} | Gets a view by ID |
| PUT | /v1/views/{id} | Replaces an existing view |
| DELETE | /v1/views/{id} | Deletes a view by ID |