English for Apache Pulsar Developers

Apache Pulsar is a distributed messaging and streaming platform built around multi-tenancy and a separation between the messaging layer (brokers) and the storage layer (BookKeeper). Its vocabulary — “tenant,” “namespace,” “subscription mode,” “tiered storage” — trips up teams coming from Kafka, where the model is flatter. This guide covers the English used when discussing Pulsar with a team.

Key Vocabulary

Tenant / namespace — Pulsar’s two-level grouping above the topic: a tenant is typically an organization or business unit, and a namespace within it groups related topics with shared policies (retention, replication). “Give the fraud team their own tenant instead of dumping their topics into the shared namespace — that way their retention policy doesn’t affect anyone else’s.”

Subscription mode (exclusive, shared, failover, key-shared) — the setting that determines how multiple consumers on the same subscription share a topic’s messages, from one consumer only to load-balanced key-based distribution. “Switch this from shared to key-shared mode — right now messages for the same user can land on two different consumers out of order, and key-shared guarantees per-key ordering.”

Broker vs. bookie — Pulsar’s split architecture: brokers handle routing, dispatch, and client connections, while bookies (BookKeeper nodes) handle the actual durable storage of message data. “Scaling brokers gives us more connection and dispatch capacity, but it doesn’t add storage — for that we need to scale the bookies.”

Tiered storage — the ability to automatically offload older message segments from BookKeeper to cheaper object storage (like S3) while keeping them queryable, without a separate archival pipeline. “We don’t need a custom archival job for old segments — tiered storage offloads them to S3 automatically once they age past the configured threshold.”

Geo-replication — Pulsar’s built-in mechanism for replicating topics across clusters in different regions, configured at the namespace level rather than per-topic. “Enable geo-replication on the namespace, not on each topic individually — new topics created under it inherit the replication policy automatically.”

Common Phrases

• “Should this live in its own tenant, or is it fine sharing a namespace with the other services?”
• “Which subscription mode do we need here — do consumers need strict per-key ordering, or is shared load-balancing fine?”
• “Is this a broker capacity problem or a bookie storage problem?”
• “Have we set a tiered storage threshold for this namespace, or is everything staying on hot storage indefinitely?”
• “Is geo-replication configured at the namespace level, and does every topic under it need to replicate?”

Example Sentences

Reviewing a pull request: “This consumer group is on shared subscription mode but expects strict ordering per user — switch to key-shared or you’ll keep seeing out-of-order processing.”

Explaining a design decision: “We split billing and analytics into separate tenants so a retention policy change on one side can never accidentally affect the other.”

Describing an incident: “Storage costs spiked because tiered storage wasn’t enabled on that namespace — every message stayed on expensive hot storage instead of offloading to S3.”

Professional Tips

• Say “tenant” and “namespace” deliberately, not just “topic group” — the two-level model is central to how Pulsar isolates teams and policies.
• When debugging ordering issues, ask “what subscription mode is this consumer on?” — it’s usually the first thing to check before suspecting the producer.
• Distinguish broker and bookie explicitly when discussing scaling — conflating them leads to scaling the wrong tier and not fixing the bottleneck.
• Mention tiered storage thresholds specifically when proposing cost reductions — it’s Pulsar’s built-in answer to “how do we cheaply keep old data queryable.”

Practice Exercise

1. Explain in two sentences the difference between a tenant and a namespace in Pulsar.
2. Write a one-sentence code review comment recommending a subscription mode change to fix ordering.
3. Describe, in your own words, what tiered storage does and why it matters for cost.

Communicating Changes in a Multi-Tenant Environment

As a developer working with Apache Pulsar’s multi-tenant namespaces – a critical feature for organizations managing multiple applications or teams within a single cluster – clear and precise communication is paramount. The terminology around these configurations can be dense, and misunderstandings can quickly lead to operational issues. It’s not simply about stating what you did; it’s about articulating why you did it, the potential impact, and how others should interpret your changes. A common pitfall for non-native English speakers is using overly technical jargon without context, leading to confusion. For example, simply saying “Modified namespace ‘production’” isn’t enough. You need to convey the scope of the change and its implications.

Consider a Slack message during a code review: “Just updated the ‘marketing-campaign’ namespace in the Pulsar cluster. Adjusted the retention policy to 7 days to align with our GDPR requirements. This ensures we’re only retaining campaign data for the legally mandated period, reducing storage costs.” The key here is explicitly linking the technical action (retention policy) to a business requirement (GDPR). Using phrasing like “aligned” and “ensures” adds clarity and demonstrates an understanding of the broader context. Furthermore, proactively anticipating questions – “Does this affect any other namespaces?” or “How does this relate to our existing data retention policies?” – showcases proactive communication skills valued in collaborative development environments. It’s also crucial to consistently use established terminology; for instance, referring to “data retention” instead of vague descriptions like “how long we keep things.”

Another example appears within a Pull Request description: “Implemented a tiered storage strategy for the ‘analytics’ namespace using Pulsar’s native capabilities. Data is automatically moved from high-performance SSD storage (tier 1) to lower-cost HDD storage (tier 2) after 30 days based on access frequency. This optimizes our cost structure without impacting query performance, as we’ve configured a dynamic indexing strategy for tier 2 data.” Here, the description breaks down a complex configuration into digestible components – tiered storage, SSD/HDD distinction, and dynamic indexing – each explained with clear consequences (“optimizes our cost structure,” “without impacting query performance”). This level of detail demonstrates technical competence and allows reviewers to quickly assess the change’s impact. Remember to always frame changes in terms of benefits rather than just describing what you did.

Finally, when discussing these configurations with stakeholders outside of development, using plain language is essential. Avoid technical jargon and focus on the business value – cost savings, improved data governance, or enhanced performance. A simple explanation like, “We’ve adjusted how long we store marketing campaign data to comply with regulations, which will also help us reduce our storage costs” is far more effective than a detailed technical explanation that might be misunderstood.

# Example Pulsar CLI command to list namespace configurations:
pulsar_cli namespaces ls --tenant "marketing-campaign"