Configure gRPC Source

The gRPC Source Source A connection to an external system that Drasi monitors for data changes. Learn more exposes a gRPC server endpoint that external applications can use to push change events (insert/update/delete) into Drasi Server Drasi Server A standalone Data Change Processing server running as a process or Docker container. Learn more .

It’s a good fit when you already have gRPC in your stack and want a typed, high-throughput ingestion path.

When to use the gRPC source

• Ingest high-volume change events from services that already communicate over gRPC.
• Stream telemetry / IoT readings into Drasi with low per-event overhead.
• Feed Drasi from a CDC pipeline that can emit protobuf messages.
• Build a language-agnostic integration using generated gRPC client stubs.

Prerequisites

• Your producer application can connect to the gRPC endpoint (host:port) over the network.
• A gRPC client implementation for your language (generated from the protobuf schema).

Quick example (Drasi Server config)

Drasi Server source configuration uses camelCase keys.

sources:
  - kind: grpc
    id: grpc-events
    autoStart: true

    host: 0.0.0.0
    port: 50051

    # Optional
    endpoint: null
    timeoutMs: 5000

If you run Drasi Server in Docker, remember to publish the gRPC port:

# docker-compose.yml (snippet)
services:
  drasi-server:
    image: ghcr.io/drasi-project/drasi-server:latest
    ports:
      - "8080:8080"     # Drasi Server REST API
      - "50051:50051"   # gRPC source

Connecting and sending events

The gRPC source implements the drasi.v1.SourceService service from the Drasi Core gRPC source plugin.

Service methods

• SubmitEvent (unary): submit a single change event.
• StreamEvents (streaming): stream many change events; the server periodically replies with progress.
• HealthCheck (unary): basic health status.
• RequestBootstrap (server streaming): currently returns an empty stream (placeholder).

Event schema (protobuf)

Change events are represented by drasi.v1.SourceChange.

• For insert/update operations, send an Element (either a Node or Relation).
• For delete operations, send ElementMetadata (so Drasi can identify what to remove).

Key types (simplified):

// drasi/v1/common.proto
message SourceChange {
  ChangeType type = 1;                 // INSERT, UPDATE, DELETE
  oneof change {
    Element element = 2;               // insert/update
    ElementMetadata metadata = 3;      // delete
  }
  google.protobuf.Timestamp timestamp = 4;
  string source_id = 5;
}

message ElementMetadata {
  ElementReference reference = 1;
  repeated string labels = 2;
  uint64 effective_from = 3;           // nanoseconds since Unix epoch
}

message ElementReference {
  string source_id = 1;
  string element_id = 2;
}

Quick smoke test with grpcurl

List services:

grpcurl -plaintext localhost:50051 list

Health check:

grpcurl -plaintext localhost:50051 drasi.v1.SourceService/HealthCheck

For complete client examples (Python/Go) and full request payloads, see the plugin README linked below.

Configuration reference (Drasi Server)

Performance tuning notes

• Prefer StreamEvents for high-throughput ingestion; it avoids per-RPC overhead.
• Reuse a single gRPC channel from your producer instead of reconnecting per event.
• If you need isolation by producer, run multiple gRPC sources on different ports (distinct ids).

Troubleshooting

Connection refused

• Ensure the source is started (autoStart: true or started via the server API).
• Verify Docker port publishing and firewall rules.

HealthCheck fails

• Confirm you are using -plaintext (no TLS) when testing with grpcurl.

“Invalid event data” responses

• Ensure you are sending SourceChange with the correct type and matching change field.
• For delete operations, include metadata.reference.element_id and metadata.labels.

Known limitations

• No server-side TLS configuration (plaintext gRPC).
• RequestBootstrap currently returns an empty stream.
• endpoint and timeoutMs are accepted by Drasi Server configuration but are currently not enforced/used by the plugin implementation.

Documentation resources