Instana Application Catalog API

openapi: 3.2.0
info:
  contact:
    email: support@instana.com
    name: © Instana
    url: http://instana.com
  termsOfService: https://www.instana.com/terms-of-use/
  title: Instana REST API documentation Application Catalog API
  version: 1.307.1417
  x-ibm-ahub-try: true
  x-logo:
    altText: instana logo
    backgroundColor: '#FAFBFC'
    url: header-logo.svg
  description: Searching for answers and best pratices?
servers:
- description: Instana Backend
  url: https://{unit}-{tenant}.instana.io
  variables:
    tenant:
      default: tenant
      description: Customer tenant unit
    unit:
      default: unit
      description: Customer tenant name
- description: Instana Self-Hosted Backend
  url: https://{domain}
  variables:
    domain:
      default: example.com
      description: Customer Self-Hosted domain
tags:
- name: Application Catalog
  description: The endpoints of this group retrieve all available resources to query application metrics.
paths:
  /api/application-monitoring/catalog:
    get:
      operationId: getApplicationTagCatalog
      parameters:
      - description: 'The start of the timestamp expreseed in Unix epoch time in milliseconds which will fetch list of queryable tags until current timestamp.

          Eg: `1719875833000` (1 July 2024 23:17:13 GMT) will fetch list of queryable tags from that time till current time.

          '
        in: query
        name: from
        schema:
          type: integer
          format: int64
      - description: The source from where queryable tags should be fetched from. In Unbounded Analytics, Application Perspectives has 2 sources; `Calls` and `Traces`.
        in: query
        name: dataSource
        schema:
          type: string
          enum:
          - CALLS
          - TRACES
      - description: 'The subset of queryable tags that is available for a particular use case.

          For eg: If you select `dataSource` as `TRACES` and useCase as `Grouping`. The tags available for querying are `trace.endpoint.name` and `trace.service.name`.

          useCase is helpful when one wants to know which tags are supported for querying.

          '
        in: query
        name: useCase
        schema:
          type: string
          enum:
          - GROUPING
          - FILTERING
          - SERVICE_MAPPING
          - SMART_ALERTS
          - SMART_ALERTS_LOGS
          - SMART_ALERTS_ADAPTIVE_BASELINE
          - SMART_ALERTS_CUSTOM_PAYLOAD
          - SLI_MANAGEMENT
          - APPLICATION_CONFIG
          - APPLICATION_CONFIG_BLUEPRINT
          - MAINTENANCE_WINDOWS
          - BIZOPS_CUSTOM_DASHBOARDS_FILTERING
      responses:
        '200':
          content:
            application/json:
              example:
                tagTree:
                - label: Agent
                  description: null
                  icon: null
                  children:
                  - label: Zone
                    icon: lib_views_tag
                    tagName: agent.zone
                    queryable: true
                    type: TAG
                  type: LEVEL
                  queryable: false
                tags:
                - name: marathon.label
                  label: Label
                  type: KEY_VALUE_PAIR
                  description: marathon label
                  canApplyToSource: true
                  canApplyToDestination: true
                  idTag: false
              schema:
                $ref: '#/components/schemas/TagCatalog'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get application tag catalog
      tags:
      - Application Catalog
      x-ibm-ahub-byok: true
      description: 'Use this API endpoint to retrieve a list of tags.

        This API endpoint also shows tags which are grouped together. This grouping also denotes the dimensionality of an event. Eg: `Call` can have 9 attributes.

        Also these tags have cardinality ranging from low to high which will help in examining broad or narrow patterns during the analysis.

        Queryable tags are a powerful enabler for slice and dice analysis in `Query Builder`. `Query Builder` can be found in `Unbounded Analytics`.'
  /api/application-monitoring/catalog/metrics:
    get:
      operationId: getApplicationCatalogMetrics
      responses:
        '200':
          content:
            application/json:
              example:
              - metricId: calls
                label: Call count
                formatter: NUMBER
                description: Number of received calls
                aggregations:
                - PER_SECOND
                - SUM
                defaultAggregation: null
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricDescription'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get Metric catalog
      tags:
      - Application Catalog
      x-ibm-ahub-byok: true
      description: This endpoint retrieves all available metric definitions for application monitoring.
  /api/application-monitoring/catalog/tags:
    get:
      deprecated: true
      operationId: getApplicationTags
      parameters:
      - description: 'The start of the timestamp expreseed in Unix epoch time in milliseconds which will fetch list of queryable tags until current timestamp.

          Eg: `1719875833000` (1 July 2024 23:17:13 GMT) will fetch list of queryable tags from that time till current time.

          '
        in: query
        name: from
        schema:
          type: integer
          format: int64
      - description: The source from where queryable tags should be fetched from. In Unbounded Analytics, Application Perspectives has 2 sources; `Calls` and `Traces`.
        in: query
        name: dataSource
        schema:
          type: string
          enum:
          - CALLS
          - TRACES
      - description: 'The subset of queryable tags that is available for a particular use case.

          For eg: If you select `dataSource` as `TRACES` and useCase as `Grouping`. The tags available for querying are `trace.endpoint.name` and `trace.service.name`.

          useCase is helpful when one wants to know which tags are supported for querying.

          '
        in: query
        name: useCase
        schema:
          type: string
          enum:
          - GROUPING
          - FILTERING
          - SERVICE_MAPPING
          - SMART_ALERTS
          - SMART_ALERTS_LOGS
          - SMART_ALERTS_ADAPTIVE_BASELINE
          - SMART_ALERTS_CUSTOM_PAYLOAD
          - SLI_MANAGEMENT
          - APPLICATION_CONFIG
          - APPLICATION_CONFIG_BLUEPRINT
          - MAINTENANCE_WINDOWS
          - BIZOPS_CUSTOM_DASHBOARDS_FILTERING
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get application tags
      tags:
      - Application Catalog
      x-ibm-ahub-byok: true
      description: '**Note:** This API Endpoint is deprecated. Use `Get application tag catalog` endpoint instead.


        This endpoint retrieves all available tags for your monitored system.


        These tags can be used to group metric results.

        ```

        "group": {

        "groupbyTag": "service.name"

        }

        ```


        These tags can be used to filter metric results.

        ```

        "tagFilters": [{

        "name": "application.name",

        "operator": "EQUALS",

        "value": "example"

        }]

        ```'
components:
  schemas:
    Tag:
      type: object
      description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.

        Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.

        '
      properties:
        aliases:
          type: array
          description: 'List of other names that can refer to this tag

            '
          items:
            type: string
            description: 'List of other names that can refer to this tag

              '
          uniqueItems: true
        availability:
          type: array
          description: 'List of product areas this tag is available in

            '
          items:
            type: string
            description: 'List of product areas this tag is available in

              '
            enum:
            - INFRASTRUCTURE_METRICS
            - APPLICATION
            - WEBSITE
            - MOBILE_APP
            - EUM
            - EUM_IMPACTED_BEACON
            - EVENT
            - SLI
            - SLO
            - SLO_PREVIEW
            - USAGE
            - LOG
            - SYNTHETICS
            - SYNTHETICS_DETAIL
            - APDEX
            - BIZOPS
            - BUSINESS_METRICS
            - SUBTRACE
            - UNKNOWN
          uniqueItems: true
        canApplyToDestination:
          type: boolean
          description: 'Whether the tag is available for destination or not.

            If source and destination is false, it means the tag is independent of source and destination. Eg: of such tag is `call.http.path`.

            '
        canApplyToSource:
          type: boolean
          description: 'Whether the tag is available for source or not.

            If source and destination is false, it means the tag is independent of source and destination. Eg: of such tag is `call.http.path`.

            '
        description:
          type: string
          description: The description of the tag if it is provided.
        idTag:
          type: boolean
          description: 'Whether the Tag is a unique ID or not.

            Eg: `idTag` for `endpoint.id` is true but for `call.rpc.method` it is false.

            '
        label:
          type: string
          description: 'The name of the tag which is seen in the UI. Eg: `Call name`'
          maxLength: 256
          minLength: 0
        name:
          type: string
          description: 'The name of the tag. Eg: `call.name`'
        type:
          type: string
          description: 'The data type of the tag. Eg: `call.name` accepts `STRING` value.'
          enum:
          - BOOLEAN
          - STRING
          - NUMBER
          - STRING_SET
          - STRING_LIST
          - KEY_VALUE_PAIR
          - FLOAT_LIST
          - KEY_NUMBER_PAIR
      required:
      - name
      - type
    TagTreeLevel:
      type: object
      description: 'The name of the tag dataset (tagTree) which can contain one or more tags as its attributes or children. Eg: `Call`.

        Consider this as the root of the tree where it has tags as attributes or children.

        '
      properties:
        children:
          type: array
          description: Children tags of tagTree
          items:
            $ref: '#/components/schemas/TagTreeNode'
        description:
          type: string
          description: The description provided, if any.
          maxLength: 512
          minLength: 0
        icon:
          type: string
          description: 'Each tag has an Icon which can be seen on the drop down list in Unbounded Analytics.

            If there is an icon, there will be a string associated with it.

            Eg: For for all `TAG` under `Call` tagTreeNode, the `icon` value is `lib_application_call`.

            '
          maxLength: 128
          minLength: 0
        label:
          type: string
          description: 'The name of the tagTreeNode. Eg: `Commonly Used`, `Application`.'
          maxLength: 128
          minLength: 0
        queryable:
          type: boolean
        scoreBoost:
          type: integer
          format: int32
          description: 'By default it is `null` if it is not set explictily by IBM Instana.

            The purpose of this parameter is to rank the tagTree. For eg: some set of tags are frequently used.

            Tags under `Commonly used` is frequently used, so it will come up on top of the drop down list of `Query Builder` in `Unbounded Analytics`.

            Higher the scoreBoost, higher the ranking.

            '
        type:
          type: string
          description: Type would be either `LEVEL` or `TAG` depending on whether the tag has any child tags or not respectively.
      required:
      - children
      - label
    MetricDescription:
      type: object
      properties:
        aggregations:
          type: array
          description: 'The types of aggregations that can be applied to a series of values.

            For example, `P25` is 25th percentile. Note that not all aggregations are available for metrics.

            For example, `Trace count` has only `SUM` as an aggregation whereas `Call Count` has two aggregations, `SUM` and `PER_SECOND`.

            '
          items:
            type: string
            description: 'The types of aggregations that can be applied to a series of values.

              For example, `P25` is 25th percentile. Note that not all aggregations are available for metrics.

              For example, `Trace count` has only `SUM` as an aggregation whereas `Call Count` has two aggregations, `SUM` and `PER_SECOND`.

              '
            enum:
            - SUM
            - MEAN
            - MAX
            - MIN
            - P25
            - P50
            - P75
            - P90
            - P95
            - P98
            - P99
            - P99_9
            - P99_99
            - DISTINCT_COUNT
            - SUM_POSITIVE
            - PER_SECOND
            - INCREASE
          uniqueItems: true
        defaultAggregation:
          type: string
          description: The preselected aggregation for a metric. For example, for `Call latency` the default aggregation is `MEAN`.
          enum:
          - SUM
          - MEAN
          - MAX
          - MIN
          - P25
          - P50
          - P75
          - P90
          - P95
          - P98
          - P99
          - P99_9
          - P99_99
          - DISTINCT_COUNT
          - SUM_POSITIVE
          - PER_SECOND
          - INCREASE
        description:
          type: string
          description: A description of the metric. For example, for `Call count` metric, the description would be something like `Number of received calls`
        formatter:
          type: string
          description: '* `NUMBER`: Generic number

            * `BYTES`: Number of bytes

            * `KILO_BYTES`: Number of kilobytes

            * `MEGA_BYTES`: Number of megabytes

            * `PERCENTAGE`: Percentage in scale [0,1]

            * `PERCENTAGE_100`: Percentage in scale [0,100]

            * `PERCENTAGE_NO_CAPPING`: Percentage in scale [0,1] but value could exceed 1 for example when metric is aggregated

            * `PERCENTAGE_100_NO_CAPPING`: Percentage in scale [0,100] but value could exceed 100 for example when metric is aggregated

            * `LATENCY`: Time in milliseconds, with value of 0 should not be considered a a strict 0, but considered as < 1ms

            * `NANOS`: Time in nanoseconds

            * `MILLIS`: Time in milliseconds

            * `MICROS`: Time in microseconds

            * `SECONDS`: Time in seconds

            * `RATE`: Number of occurrences per second

            * `BYTE_RATE`: Number of bytes per second

            * `UNDEFINED`: Metric value unit is not known

            '
        label:
          type: string
          description: The name of the metric. For example, `Call count`, `Erroneous calls`, `Service count` etc.
        metricId:
          type: string
          description: The unique id of the metric. For example, `calls`, `erroneousCalls`, `latency` etc.
      required:
      - aggregations
      - formatter
      - label
      - metricId
    TagTreeNode:
      type: object
      description: Children tags of tagTree
      discriminator:
        mapping:
          LEVEL: '#/components/schemas/TagTreeLevel'
          TAG: '#/components/schemas/TagTreeTag'
        propertyName: type
      properties:
        icon:
          type: string
        label:
          type: string
        type:
          type: string
          description: Type would be either `LEVEL` or `TAG` depending on whether the tag has any child tags or not respectively.
    TagCatalog:
      type: object
      properties:
        tagTree:
          type: array
          description: 'The name of the tag dataset (tagTree) which can contain one or more tags as its attributes or children. Eg: `Call`.

            Consider this as the root of the tree where it has tags as attributes or children.

            '
          items:
            $ref: '#/components/schemas/TagTreeLevel'
        tags:
          type: array
          description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.

            Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.

            '
          items:
            $ref: '#/components/schemas/Tag'
      required:
      - tagTree
      - tags
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: authorization
      type: apiKey
      description: "## Example\n\n```bash\ncurl --request GET \\\n  --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n"
x-tagGroups:
- name: Websites & Mobile Apps
  tags:
  - Website Metrics
  - Website Catalog
  - Website Analyze
  - Website Configuration
  - Mobile App Metrics
  - Mobile App Catalog
  - Mobile App Analyze
  - Mobile App Configuration
  - End User Monitoring
- name: Applications
  tags:
  - Application Metrics
  - Application Resources
  - Application Catalog
  - Application Analyze
  - Application Settings
  - Application Topology
  - Application Alert Configuration
  - Global Application Alert Configuration
- name: Infrastructure
  tags:
  - Infrastructure Analyze
  - Infrastructure Metrics
  - Infrastructure Resources
  - Infrastructure Catalog
  - Infrastructure Topology
- name: Logging
  tags:
  - Logging Analyze
- name: Synthetic Monitoring
  tags:
  - Synthetic Catalog
  - Synthetic Metrics
  - Synthetic Settings
  - Synthetic Test Playback Results
  - Synthetic Alert Configuration
- name: Logs
  tags:
  - Log Alert Configuration
- name: Events
  tags:
  - Events
  - Event Settings
- name: Automation
  tags:
  - Action Catalog
  - Action History
  - Policies
- name: Service Levels
  tags:
  - SLI Settings
  - SLI Report
  - Apdex Settings
  - Apdex Report
  - Service Levels Objective(SLO) Configurations
  - Service Levels Objective(SLO) Report
  - Service Levels Alert Configuration
  - SLO Correction Configurations
  - SLO Correction Windows
- name: AI Management
  tags:
  - AI Management
- name: Settings
  tags:
  - Custom Dashboards
  - User
  - Groups
  - Teams
  - Roles
  - Audit Log
  - API Token
  - Maintenance Configuration
  - Synthetic Calls
  - Session Settings
  - Automation Settings
  - Authentication
- name: Open Beta Features
  tags:
  - Infrastructure Analyze
- name: Closed Beta Features
  tags:
  - Infrastructure Alert Configuration
- name: Instana
  tags:
  - Releases
  - Host Agent
  - Health
  - Usage