Pushing Time Series Data

Use the command-line interface as a simple way to interact with the Time Series service gateway. The time series gateway uses the WebSocket protocol for streaming ingestion. The ingestion endpoint format is: wss://ingestion_url.

The Web Socket protocol is used rather than HTTP because it can ingest a higher volume of data, which increases performance.

You can see an example of a WebSocket implementation for time series ingestion at https://github.com/predixdev/timeseries-bootstrap.

Note: The ingestion URI and <Predix-Zone-Id> are included with the environment variables for your application when you bind your application to your time series service instance. To view the environment variables, on a command line, enter:

cf env <application_name>

For all ingestion requests, use the token you received from UAA in the Authorization: section of the HTTP Header in the form of Bearer <token from trusted issuer>.

Note: In previous releases, quality was supported as an attribute, but starting with this release, you must explicitly provide quality in each datapoint, along with the timestamp and measurement.

Example Data Ingestion Request

The following shows an example of the JSON payload for an ingestion request:

URL: wss://ingestion_url
Headers:
   Authorization: Bearer <token from trusted issuer>
   Predix-Zone-Id: <Predix-Zone-Id>
   Origin: http://<origin-hostname>/
    
  
Request Payload:
{  
   "messageId": "<MessageID>",
   "body":[  
      {  
         "name":"<TagName>",
         "datapoints":[  
            [  
               <EpochInMs>,
               <Measure>,
               <Quality>
            ]
         ],
         "attributes":{  
            "<AttributeKey>":"<AttributeValue>",
            "<AttributeKey2>":"<AttributeValue2>"
         }
      }
   ]
}

The following shows an example of the JSON payload for an ingestion request to send it in backFill mode.

URL: wss://ingestion_url
Headers:
   Authorization: Bearer <token from trusted issuer>
   Predix-Zone-Id: <Predix-Zone-Id>
   Origin: http://<origin-hostname>/
    
  
{  
   "messageId": "<MessageID>",
   "body":[  
      {  
         "name":"<TagName>",
         "datapoints":[  
            [  
               <EpochInMs>,
               <Measure>,
               <Quality>
            ]
         ],
         "attributes":{  
            "<AttributeKey>":"<AttributeValue>",
            "<AttributeKey2>":"<AttributeValue2>"
         }
      }
   ],
   "backFill": true
}

The following shows an example data ingestion request if you are using a Java client.

IngestionRequestBuilder ingestionBuilder = IngestionRequestBuilder.createIngestionRequest()
        .withMessageId("<MessageID>")
        .addIngestionTag(IngestionTag.Builder.createIngestionTag()
                .withTagName("TagName")
                .addDataPoints(
                        Arrays.asList(
                                new DataPoint(new Date().getTime(), Math.random(), Quality.GOOD),
                                new DataPoint(new Date().getTime(), "Bad Value", Quality.BAD),
                                new DataPoint(new Date().getTime(), null, Quality.UNCERTAIN)
                        )
                )
                .addAttribute("AttributeKey", "AttributeValue")
                .addAttribute("AttributeKey2", "AttributeValue2")
                .build());

String json = ingestionBuilder.build().get(0);
IngestionResponse response = ClientFactory.ingestionClientForTenant(tenant).ingest(json);
String responseStr = response.getMessageId() + response.getStatusCode();

Note: The <MessageID> can be a string or integer, and must be unique. When using an integer the <MessageID> should be between 0 and 2⁶⁴ (18446744073709551616).

Note: <BackFill> must be a boolean value. A 400 ( Bad Request ) status code will be returned if <BackFill> is set as any other data type.

See c_data_ingestion_and_consumption.html#concept_dc613f2c-bb63-4287-9c95-8aaf2c1ca6f7 for more information about the structure of a time series tag.

Acknowledgement Message

An acknowledgement message is sent back to the client for each message packet. The following example shows an acknowledgement message:

{
    "messageId": <MessageID>,
    "statusCode": <AcknowledgementStatusCode>
}

Acknowledgement status codes include:


Code	Message
202	Accepted successfully
400	Bad request
401	Unauthorized
413	Request entity too large Note: The payload cannot exceed 512KB.
503	Failed to ingest data