Kable SDKs

Ingesting usage events through a Kable library

Suggest Edits

📘

Kable SDKs allow you to start recording data in Kable with just a few lines of code.

Libraries are the easiest way to start recording events in a new API. They are easy to implement, and are instrumented to minimize latency impacts to your API.

Kable libraries require just three lines of code -- import, configure, execute. Most customers get their SDK set up in less than 5 minutes. You can read more about each of Kable's supported libraries below.

👍

Kable usage events, the basis of usage metering, can be implemented with one method, kable.record, in an afternoon.

Batching, Queuing, and Latency

Kable libraries are instrumented with configurable in-memory batching and queuing to minimize impacts to your API latency. When you call kable.record, the library does not make an immediate call to Kable to store the event. Instead, events are buffered in an in-memory queue inside your app, and flushed asynchronously.

The queue is flushed, sending events to Kable, on one of two conditions. When either condition is met, the queue is flushed:

  • Size-triggered flushing: When a queue fills up, as defined by the maximum queue size, the library flushes the queue, sending all queued events to Kable (more on maximum queue size below).
  • Time-triggered flushing: When the timer runs out, as defined by the maximum flush interval, the library flushes the queue, sending all queued events to Kable. The maximum flush interval is 10 seconds.

Configuring a Library

When initializing a Kable instance in your application, a few configurations are available to you to tune Kable to your desired settings:

  • Debug: When set to true, the library will print helpful messages to your logs. These messages can be noisy, so we don't recommend this setting for production, but it can be very helpful when first setting up Kable.
  • Maximum Queue Size: As mentioned above, Kable libraries buffer events before posting data back to Kable's servers. By default, the maximum queue size is 10. But you may choose to decrease or increase this setting to send events to Kable more or less often, respectively.
    • If you are running in a serverless environment, you should set maximum queue size to 1 so that the queue is flushed on every request.
const kable = new Kable({
  kableClientId: '<YOUR_KABLE_CLIENT_ID>',
  kableClientSecret: '<YOUR_KABLE_CLIENT_SECRET>',
  baseUrl: 'https://test.kable.io',
  debug: true,
  maxQueueSize: 3
});

kable = Kable({
  'kable_client_id': '<YOUR_KABLE_CLIENT_ID>',
  'kable_client_secret': '<YOUR_KABLE_CLIENT_SECRET>',
  'base_url': 'https://test.kable.io',
  'debug': True,
  'max_queue_size': 3
})

kableClient := kable.New(
  &kable.KableOptions{
    KableClientId:     "<YOUR_KABLE_CLIENT_ID>",
    KableClientSecret: "<YOUR_KABLE_CLIENT_SECRET>",
    Debug:             true,
    MaxQueueSize:      3,
  })

Recording Events

kable.record is at the heart of each Kable library. It wraps the events API and uses a buffer to collect many events before posting data back to Kable. A sample record call may look like the following: 

kable.record('yourcompanyuser_1234567890', { 
  userId: 'xyz123',
  messageId: 'msg_ABC123XYZ456', 
  objectCount: 12, 
  bankAccountBalance: 399.99
});

kable.record("yourcompanyuser_1234567890", { 
  "userId": "xyz123",
  "messageId": "msg_ABC123XYZ456", 
  "objectCount": 12, 
  "bankAccountBalance": 399.99
})

kableClient.Record(kable.Event{
  ClientId:  "yourcompanyuser_1234567890",
  Data: map[string]interface{}{
    "userId":         "xyz123",
    "messageId":      "msg_ABC123XYZ456",
    "objectCount":    12,
    "bankAccountBalance": 399.99,
  },
})

You should always include a customer's clientId in calls to record. The client ID tells Kable to which customer to attribute the event.

Event Idempotency

Kable uses the transactionId field on each event to ensure idempotence. If an event is received with a transactionId that has already been processed, Kable will discard the second (or third or fourth...) event as a duplicate.

Each Kable library exposes an optional transactionId field which you can set when recording an event. You can learn more about event idempotency here.

Supported Libraries

Kable currently supports libraries for Node, Python, and Go. You can find more information about each supported library later in the documentation.

If your language of choice is not yet supported, you can call the Kable API directly.

👍

If you decide to write a library for a language we don't yet offer, we would happily support it moving forward. You can find examples of our existing libraries for inspiration on GitHub.

Updated 5 months ago