Skip to content

Commit

Permalink
Better document KeyStrategy usage
Browse files Browse the repository at this point in the history
  • Loading branch information
wavejumper committed Nov 13, 2024
1 parent dd4dc7b commit 4bd2d2e
Showing 1 changed file with 25 additions and 0 deletions.
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,14 +165,39 @@ The keying strategy for data sent from Kpow's streams agent to its internal Kafk

The default key strategy uses the cluster ID, obtained via an AdminClient [describeClusters](https://kafka.apache.org/23/javadoc/org/apache/kafka/clients/admin/DescribeClusterResult.html) call. This AdminClient is created once during registry initialization and then closed. If you prefer not to have the streams registry create an AdminClient—either because your Kafka variant does not provide a cluster ID or due to security considerations—you may select an alternative key strategy from the options below.

```java
// Specify the key strategy when writing metrics to the internal Kafka topic
// props are java.util.Properties describing the Kafka Connection
KeyStrategy keyStrategy = new ClusterIDKeyStrategy(props);
// Register your KafkaStreams and Topology instances with the StreamsRegistry
registry.register(streams, topology, keyStrategy);
```

#### Client ID (default in 0.2.0 and below)

This key strategy relies on the client ID and application ID from the active KafkaStreams instance, eliminating the need for an AdminClient. However, in a multi-cluster Kpow deployment where the same application ID is used across multiple environments (e.g., staging, dev, prod), Kpow cannot determine which cluster the Kafka Streams instance is associated with.

```java
import io.factorhouse.kpow.StreamsRegistry;
import io.factorhouse.kpow.key_strategies.ClientIDKeyStrategy;

KeyStrategy keyStrategy = new ClientIDKeyStrategy();
registry.register(streams, topology, keyStrategy);
```

#### Environment name (manual)

If you have set a UI-friendly cluster name using the `ENVIRONMENT_NAME` environment variable in Kpow, you can use this environment name as the keying strategy for the streams agent.

```java
import io.factorhouse.kpow.StreamsRegistry;
import io.factorhouse.kpow.key_strategies.ManualKeyStrategy;

// This sets a manual key of `Trade Book (Staging)`, the name of the clusters environment name in Kpow's UI.
KeyStrategy keyStrategy = new ManualKeyStrategy("Trade Book (Staging)");
registry.register(streams, topology, keyStrategy);
```

### Minimum Required ACLs

If you secure your Kafka Cluster with ACLs, the user provided in the Producer configuration must have permission to write to the internal Kpow topic.
Expand Down

0 comments on commit 4bd2d2e

Please sign in to comment.