Integrate with Telemetry Data Collectors

Overview

Observability allows you to monitor and understand the performance and health of your systems by analyzing outputs like logs, metrics, and traces. By leveraging observability in managing your services and infrastructure, you gain valuable insights into how your digital products are performing. This helps you track and optimize service quality, ensure compliance, and boost overall operational efficiency.

Key Features

Comprehensive Monitoring and Tracking: Track service provisioning, configuration, and performance in real time to ensure operational efficiency and accuracy.

Proactive Issue Detection and Resolution: Quickly identify and address potential service failures and network issues before they impact performance.

Resource Utilization and Scaling Insights: Assess and optimize resource usage and scaling needs to improve efficiency and manage demand effectively.

Enhanced Security and Compliance: Conduct thorough security audits and monitor compliance with policies and regulations to protect against vulnerabilities.

Data Collector Setup

You can collect Event data using various Sink Types, each designed to streamline data handling and processing. Sink Types allow you to direct your Events data into preferred destinations such as Splunk for advanced analytics, or Slack for real-time alerts. Additionally, guided documentation is available to help you set up each Sink Type effectively.

Splunk HEC Documentation

Slack

Pager Duty

Service Now

Datadog Metrics

Microsoft Teams

How to Manage Streams

A stream is a logical entity created through the Stream Management APIs. It allows you to organize telemetry data from resources that share the same set of subscriptions.

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret under the Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens section for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Fabric, contact your local Equinix Service Desk.

Step 2: Create Streams

Once your Assets are created, you will need to create a Stream to manage these Assets. Call (Beta) POST /fabric/v4/streams to create a Stream.

Sample curl request

curl -X 'POST' \
     'https://api.equinix.com/fabric/v4/streams' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Bearer Token>' \
-d 
'{
    "type": "TELEMETRY_STREAM",
    "name": "splunk1",
    "description": "subscription 1",
    "project": {
        "projectId": "300014703"
    }
}'

Response

{
    "uuid": "241372e9-79c9-4ef8-b77a-8b8176c2098b4",
    "href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4",
    "type": "TELEMETRY_STREAM",
    "name": "splunk1",
    "description": "subscription 1",
    "project": {
        "projectId": "300014703"
    },
    "enabled": true,
    "state": "PROVISIONING",
    "assetsCount": 0,
    "streamSubscriptionsCount": 0,
    "changelog": {
        "createdBy": "testuser",
        "createdDateTime": "2024-08-12T21:14:17.689103902Z"
    }
}

Step 3: Retrieve Streams

Call (Beta) GET /fabric/v4/streams/{streamId} to get your Stream details.

Sample curl request

curl -X 'GET' \
   'https://api.equinix.com/fabric/v4/streams/657400f8-d360-11e9-bb65-2a2ae2dbcce5' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <Bearer Token>’

Response

{
    "uuid": "241372e9-79c9-4ef8-b77a-8b8176c2098b4",
    "href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-    8b8176c228b4",
    "type": "STREAM_SUSBSCRIPTION",
    "name": "splunk1",
    "description": "subscription 1",
    "project": {
        "projectId": "300014703"
    },
    "enabled": true,
    "state": "PROVISIONED",
    "changelog": {
        "createdBy": "testuser",
        "createdDateTime": "2024-08-12T21:14:17.689104Z"
    }
}

Delete Streams

Call (Beta) DELETE /fabric/v4/streams/{streamId} to delete a Stream.

Sample curl request

curl -X 'DELETE' \
   'https://api.equinix.com/fabric/v4/streams/657400f8-d360-11e9-bb65-2a2ae2dbcce5' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token> '

How to Manage Subscription

Consumers can use the Subscription Management APIs to manage the delivery of telemetry data to their systems.

Before calling POST/fabric/v4/streamSubscriptions, refer to Integrating Splunk as Data Collector Document to setup Splunk. By referring to this document, you will obtain an access token and the names of events and metrics indexes.

Step 1: Create Subscription

Call (Beta) POST /fabric/v4/streamSubscriptions to create a Subscription.

Sample curl request

curl -X 'POST' \
     'https://api.equinix.com/fabric/v4/streamSubscriptions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H ' Authorization: Bearer <Bearer Token>’ \
 -d 
'{
     "type": "STREAM_SUBSCRIPTION",
     "name": "eq-splunk",
     "description": "subscription1",
     "stream": {
         "uuid": "241372e9-79c9-4ef8-b77a-8b8176c2098b4"
     },
     "sink": {
         "uri": "<protocol>://http-inputs-<host>.splunkcloud.com:<port>/<endpoint>",
         "type": "SPLUNK_HEC",
         "settings": {
             "eventIndex": "<name_of_eventIndex>",
             "metricIndex": "<name_of_metricIndex>",
             "source": "<name_of_splunk_hec>"
         },
         "credential": {
             "type": "ACCESS_TOKEN",
             "accessToken": "Splunk <Splunk AccessToken>"
         }
     }
 }'

Response

{
    "uuid": "958a9854-dc49-4ded-87bd-be4d0099355e",
    "href": "https://api.equinix.com/fabric/v4/streamSubscriptions/958a9854-dc49-4ded- 87bd-be4d0099355e",
    "type": "STREAM_SUBSCRIPTION",
    "name": " eq-splunk ",
    "description": "subscription1",
    "project": {
        "projectId": "377533000114703"
    },
    "state": "PROVISIONING",
    "enabled": true,
    "stream": {
        "href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4",
        "uuid": "241372e9-79c9-4ef8-b77a-8b8176c228b4"
    },
    "sink": {
        "uri": "<protocol>://http-inputs-<host>.splunkcloud.com:<port>/<endpoint>",
        "type": "SPLUNK_HEC",
        "credential": {
            "type": "ACCESS_TOKEN"
        },
        "settings": {
            "eventIndex": "<name_of_eventIndex>",
            "metricIndex": "<name_of_metricIndex>",
            "source": "<name_of_splunk_hec>",
        }.
    },
    "changelog": {
        "createdBy": "user1",
        "createdDateTime": "2024-08-12T21:49:21.761029359Z"
    }
}

Step 2: Retrieve Subscription

Call (Beta) GET /fabric/v4/streamSubscriptions/{streamSusbscriptionId} to get your Subscription details.

Sample curl request

curl -X 'GET' \
   'https://api.equinix.com/fabric/v4/streamSubscriptions/557400f8-d360-11e9-bb65-2a2ae2dbcce4' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <Bearer Token>'

Response

{
    "uuid": "958a9854-dc49-4ded-87bd-be4d0099355e",
    "href": "https://api.equinix.com/fabric/v4/streamSubscriptions/958a9854-dc49-4ded-87bd-be4d0099355e",
    "type": "STREAM_SUBSCRIPTION",
    "name": " eq-splunk ",
    "description": "subscription1",
    "project": {
        "projectId": "377533000114703"
    },
    "state": "PROVISIONED",
    "enabled": true,
    "stream": {
        "href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c228b4",
        "uuid": "241372e9-79c9-4ef8-b77a-8b8176c228b4"
    },
    "sink": {
        "uri": "<protocol>://http-inputs-<host>.splunkcloud.com:<port>/<endpoint>",
        "type": "SPLUNK_HEC",
        "credential": {
            "type": "ACCESS_TOKEN"
        },
        "settings": {
            "eventIndex": "<name_of_eventIndex>",
            "metricIndex": "<name_of_metricIndex>",
            "source": "<name_of_splunk_hec>",
        }
    },
    "changelog": {
        "createdBy": "user1",
        "createdDateTime": "2024-08-12T21:49:21.761029Z"
    }
}

Step 3: Delete Subscription

Call (Beta) DELETE /v4/fabric/streamSubscriptions/{streamSunscriptionId} to delete a Subscription.

Sample curl request

curl -X 'DELETE' \
   'https://api.equinix.com/fabric/v4/streamSubscriptions/557400f8-d360-11e9-bb65-2a2ae2dbcce4' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>'

How to Manage Assets

The Asset Management APIs allow you to seamlessly attach Assets like Ports, Connections, and Cloud Routers to a Stream, thereby ensuring efficient organization and monitoring of your resources. You can either use existing Assets or create new Assets to add to a Stream. There are three types of Assets:

Fabric Cloud Router (FCR). To create a Fabric Cloud Router, Call POST /fabric/v4/routers

Connections. To create Connections, Call POST /fabric/v4/connections

Ports. To create Ports, Call POST /fabric/v4/ports

Step 1: Attach Assets

Attach Assets to a Stream by calling (Beta) PUT /fabric/v4/streams/{streamId}/ {connections | ports | routers}/{connectionId | routerId | portId}

Sample curl request

curl -X 'PUT' \
   'https://api.equinix.com/fabric/v4/streams/657400f8-d360-11e9-bb65-2a2ae2dbcce5/ports/757400f8-d360-11e9-bb65-2a2ae2dbcce6' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token> ' \
-d 
'{
    "metricsEnabled": false
}'

Response

{
     "uuid": " dee885d7-a845-4873-8774-f83012e7a ",
     "href": "https://api.equinix.com/fabric/v4/streams/241372e9-79c9-4ef8-b77a-8b8176c2098b4/connections/dee885d7-a845-4873-8774-f83012e7a",
     "metricsEnabled": false
     "attachmentStatus": "ATTACHING"
}

Step 2: Retrieve Asset Details

Call (Beta) GET /fabric/v4/streams/{streamId}/{connections | ports | routers}/{connectionId | routerId | portId} to get Asset details.

Sample curl request

curl -X 'GET' \
   'https://api.equinix.com/fabric/v4/streams/657400f8-d360-11e9-bb65-2a2ae2dbcce5/ports/757400f8-d360-11e9-bb65-2a2ae2dbcce6' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <Bearer Token>'

Response

{
      "uuid": " dee885d7-a845-4873-8774-f83012e7a ",
      "href": "https://api.equinix.com/fabric/v4/stream/241372e9-79c9-4ef8-b77a-8b8176c2098b4/connections/dee885d7-a845-4873-8774-f83012e7a",
      "metricsEnabled": false,
      "attachmentStatus": "ATTACHED"
}

Step3: Delete Asset Attachement

Call (Beta) DELETE /fabric/v4/streams/{streamsId}/{ports | routers | connections}/ {connectionId | routerId | portId} to delete Asset Attachment.

Sample curl request

curl -X 'DELETE' \
   'https://api.equinix.com/fabric/v4/streams/657400f8-d360-11e9-bb65-2a2ae2dbcce5/ports/757400f8-d360-11e9-bb65-2a2ae2dbcce6' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Bearer Token>'

Receive Events in Client Sink Integration

You can generate events in different ways.

BGP State Events - FCR related connections will create BGP events--BGP IPV4/IPv6 Idle, Connected, or Established--when the customer configures BGP and uses an action in the portal such as disable, enable, or reset.

Route Quota Usage Events - FCR and FCR related connections can learn IPV4/IPv6 routes up to 90% or 100% of the FCR Package Type. These routes are usually learned based on the IPV4/IPv6 addresses configured in BGP.

Port and Connection Up/Down Events - These are usually critical to the user. If the Equinix Port goes down, it will also send a Port and Connection Down Event. Once the Equinix Port recovers, it will send a Port and Connection Up Event.

Once you create a subscription, the product observability platform will send Events or Metrics to the subscribed consumers whenever the specified Events or Metrics occur. For your FCR to Port Connection, set up the Direct and BGP routing protocol and enable or disable the BGP:

1) Log in to Fabric Portal.

2) Navigate to Connection Inventory.

3) Open Connection Asset that is attached to Streams.

4) Navigate to the Routing Protocol tab.

5) Enable or Disable BGP Ipv4/Ipv6 Routing Protoc

6) Splunk will receive an Event.

Once your subscriptions are active, go to Splunk and search using index="<name_of_splunk_hec>". This search should return the relevant Event data collected by Splunk.

{ [-]
   _source: https://api.equinix.com/fabric/v4/cloudevents
   equinixmessage: Virtual port status changed to UP
   id: 5345e011-4478-484b-beb4-38c940ff2f9e
   severitynumber: 9
   severitytext: INFO
   subject: /fabric/v4/ports/c4d85dbe-f965-9659-f7e0-306a5c00af26
   time: 2024-07-26T12:31:53.975Z
   type: equinix.fabric.port.status.up
}
Show as raw text
host = http-inputs-equinix-digin.splunkcloud.com
source = Equinix
sourcetype = _json