Which APIC-EM APIs are used to manage path trace?

[Nathan Sowatskey]

Hi

Which APIC-EM APIs can be used to create and start a path trace please?

Many thanks

Nathan

[Joe Clarke]

The flow-analysis APIs deal with path analysis.

POST to /flow-analysis with a flow definition (tuple) will create a new trace, while a GET on the same resource will retrieve the results.

[Nathan Sowatskey]

Thank you Joe.

I was able to use the GET /flowanalysis to get the pre-defined path analyses. The data structure includes an ID that I would have expected to be able to use in a request to initiate the given path analysis.

There does not appear to be an API that allows me to start a path analysis given the ID though.

Am I missing something please?

Many thanks

Nathan

[yawming]

Cisco DevNet Learning Labs

Lab 4: Path Trace - Flow Analysis APIs

[Nathan Sowatskey]

Yawming

Thank you for the pointer to the learning labs, that is very useful.

I still see a disconnect in the API design with respect to the use of IDs to access existing configured path traces.

To illustrate what I mean, in inventory one can access the available devices, obtain a device ID, and then use that ID for other device inventory related APIs. This is a common pattern in REST APIs.

It seems that one can't do that with the path trace/flow analysis APIs though (or discovery). It looks like one can configure path trace, or discovery, via the UI, but one cannot interact with what one has created via the UI.

Further, it seems that, whilst in the UI one can start an existing path trace of discovery, there is no API for that logical function. Since the applications are supposed to be based on the same REST APIs, this implies that there is something missing here, probably in my understanding of the APIs.

Regards

Nathan

[yawming]

Hi Nathan,

"It looks like one can configure path trace, or discovery, via the UI, but one cannot interact with what one has created via the UI."

Can you please let us  know what do you like to do by "interacting" with what one has created via the UI.

Thanks,

Yamwing

[Joe Clarke]

I'm in the same boat as Yawming here.  I'm not clear what you're asking.  Let me give you an example of the API flow.  I have run a path trace via the GUI.  If I then go and do a GET on /flow-analysis (without specifying any other parameters), I get:

{
      "sourceIP": "192.168.1.42",
      "destIP": "172.16.2.50",
      "periodicRefresh": true,
      "id": "861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16",
      "status": "COMPLETED",
      "createTime": 1468879237948,
      "lastUpdateTime": 1468879238592
},

In that I get an ID.  I can then do:

GET /flow-analysis/861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16

And I get:

{
  "response": {
    "request": {
      "sourceIP": "192.168.1.42",
      "destIP": "172.16.2.50",
      "periodicRefresh": true,
      "id": "861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16",
      "status": "COMPLETED",
      "createTime": 1468879237948,
      "lastUpdateTime": 1468879429865
    },
    "lastUpdate": "Mon Jul 18 22:03:58 UTC 2016",
    "networkElementsInfo": [
      {
        "id": "b06913b9-8adc-469f-bf40-1d84e1c6dfdc",
        "type": "wired",
        "ip": "192.168.1.42",
        "linkInformationSource": "Switched"
      },
      {
        "id": "1153fb76-06dd-4c61-9aa6-739e3d4ab80f",
        "name": "csr-1000v.marcuscom.com",
        "type": "Routers",
        "ip": "192.168.1.48",
        "ingressInterface": {
          "physicalInterface": {
            "id": "8f6e73c0-7dee-4c5b-9b66-6bb55010fbbb",
            "name": "GigabitEthernet1"
          }
        },
        "egressInterface": {
          "physicalInterface": {
            "id": "8f6e73c0-7dee-4c5b-9b66-6bb55010fbbb",
            "name": "GigabitEthernet1"
          }
        },
        "role": "BORDER ROUTER",
        "linkInformationSource": "CONNECTED"
      },
      {
        "id": "fc422371-9e65-4e08-8e7c-5f57d3e63ade",
        "name": "pi-rsquared.marcuscom.com",
        "type": "Routers",
        "ip": "192.168.1.39",
        "ingressInterface": {
          "physicalInterface": {
            "id": "7bb4840f-086e-4eb0-944d-471e2ae9e97e",
            "name": "GigabitEthernet0/1/1"
          }
        },
        "egressInterface": {
          "physicalInterface": {
            "id": "7bb4840f-086e-4eb0-944d-471e2ae9e97e",
            "name": "GigabitEthernet0/1/1"
          }
        },
        "role": "BORDER ROUTER",
        "linkInformationSource": "Switched"
      },
      {
        "id": "1fbed996-8f4c-40ad-8275-a3ecaa0b3573",
        "type": "wired",
        "ip": "172.16.2.50"
      }
    ],
    "detailedStatus": {
      "aclTraceCalculation": "SUCCESS"
    }
  },
  "version": "1.0"
}

This would work the same if I did a POST to create (and start) a new path trace using the API.  But in this case, the POST will return:

{
  "response": {
    "flowAnalysisId": "d9fb1175-957d-4cd3-88b2-2f788cc18309",
    "taskId": "12f3521d-bd8a-4f8e-8824-034a8ff05595",
    "url": "/api/v1/flow-analysis/d9fb1175-957d-4cd3-88b2-2f788cc18309"
  },
  "version": "1.0"
}

And then I can use the flowAnalysisId in my subsequent GET to get the details.

[Nathan Sowatskey]

Joe and Yawchen

Many thanks for persevering with this.

What I was looking for was a way to trigger a path trace/flow analysis. That is not how the system works however.

The path traces are actually executed, by default, every 30 seconds once they have been created. So, one does not need to "start" a path trace per se, one just needs to do what you did above, Joe, and get the results for a given path trace.

Since that path trace will have been run at some point in the last 30 seconds or so, those results will be reasonably up to date.

This is workable, so long as one leaves the default "Periodic Refresh" of seconds selected when one starts a new path trace in the UI.

If one wants to create a path trace that can be executed on demand at some point after it has initially been created, though, I don't see a way to do that in the UI or in the API.

I think that this operational model is incomplete. The way that path traces are explained is that they are used, ad hoc, for a given support case. One would not expect, then, that the same path trace would need to be executed periodically thereafter. Once the support case is closed, then the specific path trace created for it has no purpose.

In a live system, one might expect that many such path traces would be created. Over time, with each path trace have a default refresh of 30 seconds, there would be many such path traces executing every 30 seconds, that would place a load on the system for no operational purpose.

I think that the path trace operational model should have the option of creating a path trace that is triggered on demand. I also think that the default of refreshing the path trace every 30 seconds is not a sensible default for the reasons explained above. A further improvement would be to automatically remove path trace configurations 24 hours, say, after they had last been manually started.

I would expect a case handling workflow to follow these steps:

1. - Receive problem report
2. - Create and execute path trace
3. - Identify issue
4. - Remediate issue
5. - Re-execute path trace to confirm that issue has been remediated
6. - Delete path trace

That workflow can be supported, I think, but only by recreating the same path trace configuration at 2 and 5, and by ensuring that the default of the 30 second refresh is not selected, as one would not want the path trace to be executing during 3 and 4. 

Regards

Nathan