gRPC (protobuf definitions) - Sift

Overview

Sift’s gRPC API is designed for high-frequency telemetry ingestion and real-time analysis, offering optimized performance and scalability. It uses Protocol Buffers for defining services and messages, enabling efficient, high-throughput communication. You can interact with Sift’s gRPC API in multiple ways:

Directly using standard tools like grpcurl or by writing your own gRPC clients.
Using Sift’s pre-built client libraries, available for select programming languages to simplify setup.

Sift’s client libraries internally use the gRPC API. If a client library is not available for your preferred language, you can manually generate client code from Sift’s Protocol Buffers or use command-line tools to interact with the gRPC API.
To learn how to authenticate with the gRPC API, see Authenticate with the gRPC API.
Client libraries use gRPC interceptors to automate authentication and request handling.

Listing services from the command line

You can use grpcurl to explore Sift’s available gRPC services directly from the command line.

grpcurl $SIFT_GRPC_BASE_URL:$PORT_NUM list

Replace $SIFT_GRPC_BASE_URL and $PORT_NUM with your actual gRPC endpoint and port.
When running a grpcurl command, do not include https:// in the base URL. The base URL should consist only of the hostname without any protocol prefix.
The $PORT_NUM placeholder should be replaced with 443, which is the required port for the gRPC base URL in all environments.

Official client libraries to connect with Sift’s gRPC API

Sift provides pre-built client libraries for select programming languages, designed to simplify and accelerate integration with Sift’s gRPC API. Sift’s official client libraries internally use the gRPC API. These libraries offer helpful utilities and reduce the boilerplate required to get started. All libraries are open source and maintained in the Sift GitHub repository. Supported languages:

Language	Library	Quickstart	Documentation
Python	sift-stack-py	Example	Python documentation
Rust	sift_rs	Example	Rust documentation
Go	github.com/sift-stack/sift/go	Example	Go documentation

Using other languages to connect with Sift’s gRPC API

If your preferred language doesn’t yet have a dedicated client library, you can instead:

Compile Sift’s Protocol Buffers manually to generate gRPC client code in your preferred language.
Use the Sift REST API, which provides a standard HTTP-based interface for integration.

URL formatting for official gRPC clients

The required format for official gRPC API URLs depends on your client library. Some libraries require you to omit the URL scheme and port number, while others expect them to be included. Refer to the documentation of your chosen client library to confirm the expected URL format.

Language	Requires `https://` prefix	Requires port number
Python	No	No
Rust	Yes	No
Go	No	Yes

The gRPC API uses port 443 by default in all environments.

Quickstart: Connect to the gRPC API with an official Sift client

Python

To quickly connect with Sift’s Python client, consider the following steps:

Create a Python environment.
```
  python3 -m venv venv 
```
In your Python environment (venv) install the Sift Python package:
```
pip install sift-stack-py
```

In your Python environment directory, create a file named main.py and paste the following code:

import os

from sift.ping.v1.ping_pb2 import PingRequest
from sift.ping.v1.ping_pb2_grpc import PingServiceStub
from sift_py.grpc.transport import SiftChannelConfig, use_sift_channel

if __name__ == "__main__":
    apikey = os.getenv("SIFT_API_KEY")
    assert apikey

    uri = os.getenv("SIFT_GRPC_BASE_URL")
    assert uri

    channel_config: SiftChannelConfig = {
        "apikey": apikey,
        "uri": uri,
    }

    with use_sift_channel(channel_config) as channel:
        response = PingServiceStub(channel).Ping(PingRequest())
        print(response)

In your Python environment directory, run the following command after replacing the placeholders ($SIFT_API_KEY and $SIFT_GRPC_BASE_URL) with your actual values:
```
SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY python main.py
```
- $SIFT_API_KEY: To learn how to create an API key, see Create an API key.
- $SIFT_GRPC_BASE_URL:
  - The Python client allows you to omit the URL scheme and port number.
  - To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.

Rust

To quickly connect with Sift’s Rust client, consider the following steps:

Create a Rust project.
```
cargo new my_sift_project
```
In your Rust project, add the sift_rs crate.
```
cd my_sift_project
cargo add sift_rs
```
In your Rust project, add the tokio runtime.
```
cargo add tokio --features full
```

Copy and paste the following into your my_sift_project/src/main.rs:

use sift_rs::{
    Credentials, SiftChannelBuilder,
    ping::v1::{PingRequest, ping_service_client::PingServiceClient},
};
use std::env;

#[tokio::main]
async fn main() {
    let credentials = Credentials::Config {
        apikey: env::var("SIFT_API_KEY").unwrap(),
        uri: env::var("SIFT_GRPC_BASE_URL").unwrap(),
    };

    let conn = SiftChannelBuilder::new(credentials).build().unwrap();
    let mut ping_service = PingServiceClient::new(conn);
    let ping_response = ping_service.ping(PingRequest::default()).await.unwrap();

    println!("{}", ping_response.into_inner().response);
}

In your Rust project directory, run the following command after replacing the placeholders ($SIFT_API_KEY and $SIFT_GRPC_BASE_URL) with your actual values:
```
SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY cargo run
```
- $SIFT_API_KEY: To learn how to create an API key, see Create an API key.
- $SIFT_GRPC_BASE_URL:
  - The Rust client requires you to add the URL scheme while adding the port number is optional.
  - To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.

Go

To quickly connect with Sift’s Go client, consider the following steps:

Set up a dedicated directory and initialize it as a Go module using go mod:

mkdir go-client-connection && cd go-client-connection
go mod init sift_go_project

Use go get to fetch the Sift Go SDK and include it in your project:
```
go get github.com/sift-stack/sift/go
```

In the sift_go_project directory, create a main.go file and copy and paste the following into that file:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/sift-stack/sift/go/gen/sift/ping/v1"
    "github.com/sift-stack/sift/go/grpc"
)

func main() {
    ctx := context.Background()
    channelConfig := grpc.SiftChannelConfig{
        Uri:    os.Getenv("SIFT_GRPC_BASE_URL"),
        Apikey: os.Getenv("SIFT_API_KEY"),
    }
    conn, err := grpc.UseSiftChannel(ctx, channelConfig)
    if err != nil {
        log.Fatalln(err)
    }
    pingClient := pingv1.NewPingServiceClient(conn)
    res, err := pingClient.Ping(ctx, &pingv1.PingRequest{})
    if err != nil {
        log.Fatalln(err)
    }
    fmt.Println(res.Response)
}

Verify and tidy up your module dependencies:
```
go mod tidy 
```
In your Go module, run the following command after replacing the placeholders ($SIFT_API_KEY, $SIFT_GRPC_BASE_URL, and $PORT_NUM) with your actual values:
```
SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY go run .
```
- $SIFT_GRPC_BASE_URL: The base URL for Sift gRPC requests.
  - The Go client expects the base URL without the URL scheme (for example, use api.siftstack.com, not https://api.siftstack.com).
  - To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.
- $PORT_NUM: The port number used for gRPC connections.
  - Defaults to 443 in all environments.
  - The Go client requires you to explicitly include the port number.
- $SIFT_API_KEY: Your Sift API key for authentication.
  - To learn how to generate an API key, see Create an API key.

​Overview

​Listing services from the command line

​Official client libraries to connect with Sift’s gRPC API

​Using other languages to connect with Sift’s gRPC API

​URL formatting for official gRPC clients

​Quickstart: Connect to the gRPC API with an official Sift client

​Python

​Rust

​Go