Example toolkit CLI operations

Examples of useful analytics CLI commands.

The CLI help lists all the filters that can be used when querying analytics data.

apic-slim -m analytics events:orgList -h
Usage: apic events:orgList [flags]

List events at provider organization scope.

Return a result set of analytics API events scoped to the provider organization. The items in the result set are determined by the passed in request query to this API. The order of the result set is sorted from newest to oldest events by specified 'datetime'. In this API, references to 'field' refer to the analytics API event fields documented here: https://www.ibm.com/docs/en/api-connect/10.0.5.x_lts?topic=data-api-event-record-fields

Flags:
      --accept-language string                                   Natural language and locale that the client prefers.
      --analytics-service string                                 Analytics service name or ID. (required)
      --api_id string                                            Filter results by API ID.
      --api_name string                                          Filter results by API name.
      --app_id string                                            Filter results by application ID.
      --app_lifecycle_state string                               Filter results by application lifecycle state.
      --app_name string                                          Filter results by application name.
      --bytes_received string                                    Filter results by the number of bytes received.
      --bytes_sent string                                        Filter results by the number of bytes sent.
      --catalog_id string                                        Filter results by catalog ID.
      --catalog_name string                                      Filter results by catalog name.
      --client_id string                                         Filter results by client ID.
      --client_ip client_ip=9.123.234.0/24                       Filter results by client IP address. Only supports equality checks and no operator prefixes. Supports CIDR notation based queries, e.g. client_ip=9.123.234.0/24
      --consumer_org_id developer_org_id                         Filter results by consumer organization ID (filters on the developer_org_id data field).
      --consumer_org_name developer_org_name                     Filter results by consumer organization name (filters on the developer_org_name data field).
      --consumer_org_title developer_org_title                   Filter results by consumer organization title (filters on the developer_org_title data field).
      --end string                                               If set, only return events with a datetime equal or older than this. The value must follow the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z. See https://datatracker.ietf.org/doc/html/rfc3339#section-5.6.

      --endpoint_url string                                      Filter results by endpoint_url, note this field is only set on failed API events.
      --event_id string                                          If set, only return this specific event ID.
      --fields string                                            A list of the event fields that you want included in each event. You can use a comma as a separator when specifying the fields. Use this parameter if you require only a subset of the event fields rather than the full set.

      --format string                                            Output format. One of [json yaml go-template=... go-template-file=...], defaults to yaml.
      --gateway_ip gateway_ip=9.123.234.0/24                     Filter results by gateway IP address. Only supports equality checks and no operator prefixes. Supports CIDR notation based queries, e.g. gateway_ip=9.123.234.0/24
      --global_transaction_id string                             Filter results by global transaction ID.
      --graphql_request_field_cost string                        Filter results by graphql request field cost value.
      --graphql_request_type_cost string                         Filter results by graphql request type cost value.
      --graphql_response_type_cost string                        Filter results by graphql response type cost value.
      --immediate_client_ip immediate_client_ip=9.123.234.0/24   Filter results by immediate client IP address. Only supports equality checks and no operator prefixes. Supports CIDR notation based queries, e.g. immediate_client_ip=9.123.234.0/24
      --limit string                                             If set, the number of items to return when requesting a list. Maximum: 500
      --method string                                            Filter results by HTTP method e.g. DELETE, GET, POST.
      --offset string                                            If set, the offset to be applied when requesting a list. e.g. return events starting from the 100th result
  -o, --org string                                               Provider organization name or ID. (required)
      --output string                                            Write file(s) to directory, instead of STDOUT (default "-")
      --path string                                              If set, only return events that contain this path value.
      --path_id string                                           Filter results by path_id
      --plan_id string                                           Filter results by plan ID
      --plan_name string                                         Filter results by plan name
      --plan_version string                                      Filter results by plan version
      --product_id string                                        Filter results by product ID.
      --product_name string                                      Filter results by product name.
      --product_title string                                     Filter results by product title.
      --product_version string                                   Filter results by product version.
      --query_string string                                      Filter results by query_string.
      --request_body string                                      Filter results by request body.
      --resource_id string                                       Filter results by resource ID.
      --response_body string                                     Filter results by response body.
  -s, --server string                                            management server endpoint (required)
      --space_id string                                          Filter results by space ID.
      --space_name string                                        Filter results by space name.
      --start string                                             If set, only return events with a datetime equal to or newer than this. The value must follow the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z. See https://datatracker.ietf.org/doc/html/rfc3339#section-5.6.

      --status_code string                                       If set, only return events that match this response code e.g. 200 OK, 404 Not Found. It is also possible to use wildcard based values 10x, 20x, 30x, 40x, 50x.
      --time_to_serve_request string                             The time in milliseconds to serve the request.
      --timeframe string                                         If set, only return events within the indicated timeframe. This parameter will be ignored if either start or end have been specified.

Operators can be applied to these filters to provide advanced filtering.

Note: In the examples shown the full command is

apic-slim -m analytics events:orgList -s <management_fqdn> --analytics-service <analytics_service_name> --org <provider_org> --format yaml <filter>

For brevity, only the base command and filter are shown in the following examples.

Select all events with consumer organization ID of 7f9b6ee4-268d-449c-adc1-e0f3bbde8dfe.
```
apic-slim -m analytics events:orgList ... --consumer_org_id 7f9b6ee4-268d-449c-adc1-e0f3bbde8dfe
```
Note: In the API event records, consumer_org_id is referred to as developer_ord_id.
Select all events that do not have the consumer organization ID of 7f9b6ee4-268d-449c-adc1-e0f3bbde8dfe.
```
apic-slim -m analytics events:orgList ... --consumer_org_id not:7f9b6ee4-268d-449c-adc1-e0f3bbde8dfe
```

Select all events that have the product name of superproduct.

apic-slim -m analytics events:orgList ... --product_name superproduct

Select all events that have a product name that contains the string super.
```
apic-slim -m analytics events:orgList ... --product_name contains:super
```
Select all events that have a product name that does not contain the string super.
```
apic-slim -m analytics events:orgList ... --product_name notcontains:super
```
Select all events that have a product name that starts with the string super.
```
apic-slim -m analytics events:orgList ... --product_name startswith:super
```
Select all events that have a product name that ends with the string super.
```
apic-slim -m analytics events:orgList ... --product_name endswith:super
```

Select all events that have one of a list of product names.

apic-slim -m analytics events:orgList ... --product_name oneof:superproduct,normalproduct,basicproduct

Select all events that do not have one of a list of product names.

apic-slim -m analytics events:orgList ... --product_name notoneof:superproduct,normalproduct,basicproduct

Select all events where the product name matches a regex:
```
apic-slim -m analytics events:orgList ... --product_name regex:"[a-zA-Z]amlet"
```
For regex syntax and examples, see Regex syntax
Note: Regex queries are more resource intensive and so can take longer than other methods.
Select all events where the bytes received were 57.
```
--bytes_received 57
```
Select all events where the bytes received were more than or equal to 57.
```
--bytes_received gte:57
```

For numeric fields, the available comparison operators are: lt:, lte:, gt:, gte:. For text and numeric fields these prefixes available are not:, contains:, notcontains:, oneof:.

Note:

The regex operator uses the following syntax:

\ is the escape character, to be used before any of the other reserved characters, for them to applied literally.
```
a\-z matches a-z
```
[] square brackets match a single character within the brackets.
```
[01]m matches 0m or 1m
```
- denotes a range if used between two characters.
```
[a-z] matches any character between a and z, for example a, b, c, ...
```
When used at the start of the regex - matches -.
^ is a NOT operator that negates what is specified after it.
```
[^k] matches any character except for k.
```
+ denotes repetition of the preceding character at least once.
```
U$+ matches U$, U$$, U$$$, ...
```
() parentheses treat their contents as if they were a single character, for use in combination with operators that apply to preceding characters.
```
tr(cat)+ matches trcat, trcatcat, trcatcatcat
```
{} curly brackets indicate the minimum and maximum number of repetitions of the preceding character. The maximum value is unlimited if omitted with the comma, and the same as the minimum if omitted without the comma.
```
1{3,4} matches 111 and 1111
2{4} matches 2222 only.
2{4,} matches 2222, 22222, 222222,...
```
? denotes repetition of the preceding character zero or one times.
```
ti? matches t and ti
```
. matches any character.
```
da. matches daa, dab, ...
```
* denotes repetition of the preceding character zero or more times.
```
cab* matches ca, cab, cabb
```
| denotes the OR operator. The longest pattern on either side of the | matches.
```
Mb|Mi matches Mb and Mi
```
# denotes not string, not even an empty string.

& is the AND operator.

hello.+&.+rest matches hellow-world-rest

~ denotes a fuzzy logic match.

hello-world-~dt matches hello-world-test

@ matches any string.
<> angle brackets match a number range.
```
<3-15>Mb matches 3Mb, 4Mb, 5Mb, ...
```