Headers, X-NetSapiens-Log, and InSight on-demand logging

In this guide we'll be documenting the use of the X-NetSapiens-Log header in order to collect real-time on-demand logging data from InSight during API testing. Let's briefly cover what this header is, though. API headers are key-value pairs sent with HTTP requests that provide important metadata about the request or response.

Headers serve several crucial functions in API requests:
Authentication and Authorization: Headers often carry credentials that prove who you are and what you're allowed to do. The most common pattern is the Authorization header:

// Bearer token authentication like our API uses
fetch('/api/endpoint', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
});

Content Negotiation: Headers tell the server what kind of data you're sending and what you expect back. The Content-Type and Accept headers handle this:

fetch('/api/endpoint', {
  headers: {
    'Content-Type': 'application/json',  // The data we're sending is JSON
    'Accept': 'application/json'         // We want JSON back
  },
  body: JSON.stringify({ name: 'John' })
});

Custom Behavior Control: Custom headers (usually prefixed with X-) can trigger special behaviors. This is where X-NetSapiens-Log comes in:

fetch('/api/users', {
  headers: {
    'X-NetSapiens-Log': 'some tag name',     // Enable detailed logging for this request with a custom tag
    'X-Request-ID': '123e4567-e89b', // E.G. Track this request through the system
  }
});

On-Demand Logging and X-NetSapiens-Log Header

Next we'll describe the process of using the X-NetSapiens-Log header for your API testing. What follows is an example flow:

1. Create an API request for the netsapiens-api package, e.g.:
   1. curl --location --request POST 'https://www.example.com/ns-api/oauth2/token/?grant_type=password&client_id=xxxxx&client_secret=xxxxxxxxxxxxxxxxxxxx&username=1099%40xxxxxxx&password=Xxxxxxx%3F' \
2. Add the header for On-Demand logs(X-NetSapiens-Log) to the API request:
   1. curl --location --request POST 'https://qa-u22-tor10.netsapiens.com/ns-api/oauth2/token/?grant_type=password&client_id=xxxxx&client_secret=xxxxxxxxxxxxxxxxxxxx&username=1099%40xxxxxxx&password=Xxxxxxx%3F' \ --header 'X-NetSapiens-Log: LOGTAG'
   2. ...where LOGTAG is any string you want to use to search and track on
3. Execute the API request through whichever tool or interface you're using.
4. Go to iNSight application.
5. Select the appropriate organization where the servers is added.
6. Click on Search Dashboards.
7. Search for 'On-demand API and Portal Logs'.
8. Select the dashboard for OnDemand logs.
9. Enter the value for X-NetSapiens-Log under search value1, like so:

   1. 

At this point you will begin to see your API requests be logged there in the InSight panel in real time.