REST APIs : Observer REST : Extracting GigaStor data
  
Extracting GigaStor data
 
Page Contents
How to extract data to a temporary file
How to extract data to a file in a specific location
How to get the status of a trace extraction
How to download a trace file
Windows user account and trace extraction
Parameters used to extract GigaStor data
Data can be extracted from your GigaStor to a trace file allowing you to use the data in another tool for reporting or analyzing. The trace file can be .pcap, .bfr, or .pcapng.
Some options inside the Observer user interface have precedence over REST API requests. For instance, if a POST request for packet capture extraction is actively being processed and a somebody using Observer starts a GigaStor packet analysis, the POST is stopped and queued until the GigaStor packet analysis completes. After the packet analysis is completed, then the POST request is restarted from the beginning.
How to extract data to a temporary file
By default, files are extracted to a temporary location in the Observer Web Server and kept for 24 hours.
An active session
Knowledge of your base URI
Write permission
A temporary file gives you access to the data you need for reports without you needing to worry about trace files filling your hard drive. If you need to use the same data in the future and the temporary has been deleted, simply rerun the GET request.
1. To create a session, send a POST command to /obs/api/v1/session using the following request body object .
Figure 6: Select All
{
"username": "admin",
"password": ""
}
2. Send a POST command to /obs/api/v1/gs/traces using the following request body object.
Figure 7: Select All
{
"instanceName": "Instance 1",
"traceFormat": "pcap",
"traceFileName": "MyFileName",
"saveTo": "tempStorage",
"extractionTimeRange": {
"timeStart": "2016-01-27T00:00:00.000Z",
"timeEnd": "2016-01-28T00:00:00.000Z"
},
"filter": "ip 10.1.20.50[tcp/80]"
}
On success, a 202 Accepted response is returned along with a jobs object in the response body. Inside of the job, the location field indicates where the final location of the trace file will be.
 
Traces extracted to temporary storage expire and are deleted after 24 hours along with their corresponding jobs objects.
 
How to extract data to a file in a specific location
You may save your trace file to a specific, known location on the local system or a network drive by setting saveTo to specifiedPath along with defining the path. Unlike a temporary file, it is not automatically deleted after 24 hours.
An active session
Knowledge of your base URI
Write permission
1. Send a POST command to /obs/api/v1/gs/traces using the following request body object.
Any backslash (\) characters in the path must be properly escaped in the JSON. For example, "path": "G:\\UsersChoice\\Of\\Directory" or "path": "\\\\server\\share\\traces".
Figure 8: Select All
{
"instanceName": "Instance 1",
"traceFormat": "pcap",
"traceFileName": "MyFileName",
"saveTo": "specifiedPath",
"path": "G:\\UsersChoice\\Of\\Directory",
"extractionTimeRange": {
"timeStart": "2016-01-27T00:00:00.000Z",
"timeEnd": "2016-01-28T00:00:00.000Z"
},
"filter": "ip 10.1.20.50[tcp/80]"
}
 
On success, a 202 Accepted response is returned along with a jobs object in the response body. Inside of the job, the location field indicates where the final location of the trace file is.
 
How to get the status of a trace extraction
Some trace files can be large and take a while to download. Use the job ID to see how much of the file has been downloaded.
An active session
Knowledge of your base URI
Write permission
The job ID
1. From the Location HTTP header, find the location from which to get the corresponding Observer job object.
Location: '/obs/api/v1/jobs/{id}'
2. Send a GET request to the URI of the job object to retrieve the status of the trace extraction job.
The job object will indicate a job status value along with a percentage complete. Large trace files may take some time to complete. You may continue to issue GET requests for this object to update any progress indicators.
Figure 9: Select All
{
"data": {
"job": {
"id": "01FDA3B2-464D-81C6-3BFC-BCAEC5415579",
"type": "TRACE_EXTRACTION",
"status": "IN_PROGRESS",
"queuePosition": 0,
"progress": 40,
"location": "/obs/api/v1/jobs/01FDA3B2-464D-81C6-3BFC-BCAEC5415579",
"etag": "2ACD95DD7846E4119BCFBCAEC5015590"
}
}
}
 
The trace file is complete and ready to be downloaded when the jobs object progress indicates 100% and the status field is set to COMPLETE.
 
How to download a trace file
Download files into your reporting tool or analyzer to use the data in the trace file.
An active session
Knowledge of your base URI
Write permission
The job ID
The job is 100% completed.
1. Send a GET request to the URI specified inside of the job object, including the job ID, to download the trace file.
Figure 10: Select All
{
"data": {
"job": {
"id": "01FDA3B2-464D-81C6-3BFC-BCAEC5415579",
"type": "TRACE_EXTRACTION",
"status": "COMPLETE",
"etag": "2ACD95DD7846E4119BCFBCAEC5015590"
}
}
}
 
The downloaded file is available for you to use or manipulate using your other tools.
 
Windows user account and trace extraction
The Windows user account under which Observer runs and how it is running (that is, as service or application) affects where you may write trace files.
 
The target GigaStor needs disk write permissions to the specified directory or you will encounter a job error.
If the file path is to a local disk on the GigaStor and you are running in service mode, you should not encounter many write permission issues, if any at all.
If the file path is network storage (either a mapped or unmapped location) and you are running in service mode, the GigaStor Windows ‘system’ user account itself needs write permission to that directory. You could encounter write permission errors.
If you are running Observer in application mode, the Windows user account that is logged in and is the owner of the Observer process must have write permission to that directory.
 
Parameters used to extract GigaStor data
Use these options to configure your trace file extraction.
 
Parameter
Description
instanceName
String. The Observer probe instance name from which to extract the GigaStor trace. If you specify a passive instance, the trace is pulled from the passive instance’s parent active instance.
traceFormat
String. The resulting trace file format. Valid options are: pcap, bfr, or pcapng.
traceFileName
String. The resulting trace file name without an extension.
saveTo
String. The location of the resulting trace file. The tempStorage will be available for external download for 24 hours; specifiedPath files are kept indefinitely until you delete them. Valid options are: tempStorage or specifiedPath.
extractionTimeRange
TimeRangeObject. The time range for which to extract the trace.
filter
String, optional. The extraction filter criteria. Any Unicode characters used in the filter are converted to your web browser's character encoding. If a different UTF-level is required, use hexadecimal characters in the filter pattern. See Understanding the filter syntax.
path
String, optional. Required if saveTo parameter is set to specifiedPath. Indicates an absolute folder path to save the resultant trace file to on the Observer hosting the GigaStor such as C:\\myFolder\\traces.
timeStart
String. The start time of the trace file, specified in combined date and time in UTC ISO8601 format.
timeEnd
String. The end time of the trace file, specified in combined date and time in UTC ISO8601 format.