Skip to content

Commit 6cc7365

Browse files
mvallimmvallim
committed
chore: update documentation
Signed-off-by: Marcos Tischer Vallim <tischer@gmail.com>
1 parent b68005f commit 6cc7365

6 files changed

Lines changed: 172 additions & 168 deletions

File tree

‎.opencode/skills/documentation/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: "GenerateMarkdownDocs"
2+
name: "generate-markdown-docs"
33
description: "Skill that analyzes code and generates technical documentation in Markdown."
44
scope: "workspace"
55
commands:

‎GUIDE.md‎

Lines changed: 57 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,33 +4,33 @@
44

55
The library provides an asynchronous, batched messaging client for Amazon SNS, supporting both AWS SDK v1 and v2. It is organized as a multi-module Maven project:
66

7-
| Module | Artifact | Purpose |
8-
|---|---|---|
9-
| `amazon-sns-java-messaging-lib-template` | *(internal)* | SDK-agnostic core: batching, queuing, threading, metrics |
10-
| `amazon-sns-java-messaging-lib-v1` | `amazon-sns-java-messaging-lib-v1` | AWS SDK v1 implementation (`AmazonSNS` client) |
11-
| `amazon-sns-java-messaging-lib-v2` | `amazon-sns-java-messaging-lib-v2` | AWS SDK v2 implementation (`SnsClient`) |
7+
| Module | Artifact | Purpose |
8+
|------------------------------------------|------------------------------------|----------------------------------------------------------|
9+
| `amazon-sns-java-messaging-lib-template` | *(internal)* | SDK-agnostic core: batching, queuing, threading, metrics |
10+
| `amazon-sns-java-messaging-lib-v1` | `amazon-sns-java-messaging-lib-v1` | AWS SDK v1 implementation (`AmazonSNS` client) |
11+
| `amazon-sns-java-messaging-lib-v2` | `amazon-sns-java-messaging-lib-v2` | AWS SDK v2 implementation (`SnsClient`) |
1212

1313
### Core Components
1414

15-
```
16-
┌──────────────────────────────────────────────────────────┐
15+
```text
16+
┌────────────────────────────────────────────────────────────┐
1717
│ AmazonSnsTemplate<E> │
18-
├──────────────────────────────────────────────────────────┤
19-
│ ┌──────────────────────┐ ┌────────────────────────┐ │
18+
├────────────────────────────────────────────────────────────┤
19+
│ ┌───────────────────────┐ ┌─────────────────────────┐ │
2020
│ │ AmazonSnsProducer<E> │ │ AmazonSnsConsumer<R,O> │ │
21-
│ │ (AbstractProducer) │ │ (AbstractConsumer) │ │
22-
│ │ │ │ │ │
23-
│ │ - BlockingQueue │ │ - ScheduledExecutor │ │
24-
│ │ - PendingRequests │ │ - Batching Logic │ │
25-
│ └──────────┬───────────┘ └───────────┬────────────┘ │
26-
│ │ │ │
27-
│ send(E) publishBatch(...) │
28-
└─────────────┼────────────────────────────┼───────────────┘
29-
│ │
30-
▼ ▼
31-
┌──────────────────────────────────────────┐
21+
│ │ (AbstractProducer) │ │ (AbstractConsumer) │ │
22+
│ │ │ │ │ │
23+
│ │ - BlockingQueue │ │ - ScheduledExecutor │ │
24+
│ │ - PendingRequests │ │ - Batching Logic │ │
25+
│ └──────────┬────────────┘ └───────────┬─────────────┘ │
26+
│ │ │ │
27+
│ send(E) publishBatch(...) │
28+
└─────────────┼─────────────────────────────┼────────────────┘
29+
│ │
30+
▼ ▼
31+
┌───────────────────────────────────────────┐
3232
│ Amazon SNS (v1/v2) │
33-
└──────────────────────────────────────────┘
33+
└───────────────────────────────────────────┘
3434
```
3535

3636
- **`AmazonSnsTemplate`** — Main entry point. Created via a fluent builder (`AmazonSnsTemplate.builder(snsClient, topicProperty)`).
@@ -115,13 +115,13 @@ For **FIFO** topics, messages are published **synchronously** on a single-thread
115115

116116
### TopicProperty
117117

118-
| Property | Type | Default | Description |
119-
|---|---|---|---|
120-
| `fifo` | `boolean` | `false` | Whether the SNS topic is FIFO |
121-
| `topicArn` | `String` | — | The SNS topic ARN |
122-
| `maximumPoolSize` | `int` | — | Max threads for the producer pool |
123-
| `maxBatchSize` | `int` | — | Max messages per batch request |
124-
| `linger` | `long` (ms) | — | Time to wait before flushing a batch |
118+
| Property | Type | Default | Description |
119+
|-------------------|-------------|---------|--------------------------------------|
120+
| `fifo` | `boolean` | `false` | Whether the SNS topic is FIFO |
121+
| `topicArn` | `String` | — | The SNS topic ARN |
122+
| `maximumPoolSize` | `int` | — | Max threads for the producer pool |
123+
| `maxBatchSize` | `int` | — | Max messages per batch request |
124+
| `linger` | `long` (ms) | — | Time to wait before flushing a batch |
125125

126126
**Note**: The in-memory buffer size = `maximumPoolSize × maxBatchSize`. Large values consume proportionally more memory.
127127

@@ -210,41 +210,41 @@ The library integrates with Micrometer and records the following metrics when a
210210

211211
Tags: `topic` = `<topicArn>`
212212

213-
| Metric Name | Type | Description | Config |
214-
|---|---|---|---|
215-
| `sns.publish.attempts` | `Counter` | Total number of SNS PublishBatch calls attempted | — |
216-
| `sns.publish.success` | `Counter` | Individual SNS messages acknowledged as successful | — |
217-
| `sns.publish.failure` | `Counter` | Individual SNS messages that failed | Dynamic tags: `error_code`, `error_type` |
218-
| `sns.publish.duration` | `Timer` | End-to-end latency of SNS PublishBatch calls | Percentiles: 0.5, 0.95, 0.99 |
219-
| `sns.publish.batch.size` | `DistributionSummary` | Number of entries per SNS PublishBatch request | — |
220-
| `sns.publish.inflight` | `Gauge` | PublishBatches currently in progress | Backed by `AtomicInteger` |
213+
| Metric Name | Type | Description | Config |
214+
|--------------------------|-----------------------|----------------------------------------------------|------------------------------------------|
215+
| `sns.publish.attempts` | `Counter` | Total number of SNS PublishBatch calls attempted | — |
216+
| `sns.publish.success` | `Counter` | Individual SNS messages acknowledged as successful | — |
217+
| `sns.publish.failure` | `Counter` | Individual SNS messages that failed | Dynamic tags: `error_code`, `error_type` |
218+
| `sns.publish.duration` | `Timer` | End-to-end latency of SNS PublishBatch calls | Percentiles: 0.5, 0.95, 0.99 |
219+
| `sns.publish.batch.size` | `DistributionSummary` | Number of entries per SNS PublishBatch request | — |
220+
| `sns.publish.inflight` | `Gauge` | PublishBatches currently in progress | Backed by `AtomicInteger` |
221221

222222
The `sns.publish.failure` counter is created dynamically with additional `error_code` (AWS error code string) and `error_type` (amazon_service_exception or unknown) tags.
223223

224224
### Blocking Queue Metrics
225225

226226
Tags: `name` = `<queueName>`
227227

228-
| Metric Name | Type | Description | Config |
229-
|---|---|---|---|
230-
| `blocking.queue.puts.total` | `Counter` | Total number of successful put operations | — |
231-
| `blocking.queue.puts.failed` | `Counter` | Total number of put operations that threw an exception | — |
232-
| `blocking.queue.put.duration` | `Timer` | Latency of put operations (including wait time when queue is full) | Percentile histogram |
233-
| `blocking.queue.takes.total` | `Counter` | Total number of successful take operations | — |
234-
| `blocking.queue.takes.failed` | `Counter` | Total number of take operations that threw an exception | — |
235-
| `blocking.queue.take.duration` | `Timer` | Latency of take operations (including wait time when queue is empty) | Percentile histogram |
236-
| `blocking.queue.size` | `Gauge` | Current number of elements in the queue | Calls `delegate.size()` |
228+
| Metric Name | Type | Description | Config |
229+
|--------------------------------|-----------|----------------------------------------------------------------------|-------------------------|
230+
| `blocking.queue.puts.total` | `Counter` | Total number of successful put operations | — |
231+
| `blocking.queue.puts.failed` | `Counter` | Total number of put operations that threw an exception | — |
232+
| `blocking.queue.put.duration` | `Timer` | Latency of put operations (including wait time when queue is full) | Percentile histogram |
233+
| `blocking.queue.takes.total` | `Counter` | Total number of successful take operations | — |
234+
| `blocking.queue.takes.failed` | `Counter` | Total number of take operations that threw an exception | — |
235+
| `blocking.queue.take.duration` | `Timer` | Latency of take operations (including wait time when queue is empty) | Percentile histogram |
236+
| `blocking.queue.size` | `Gauge` | Current number of elements in the queue | Calls `delegate.size()` |
237237

238238
### Executor Metrics
239239

240240
Tags: `name` = `<executorName>`
241241

242-
| Metric Name | Type | Description | Config |
243-
|---|---|---|---|
244-
| `executor.active` | `Gauge` | Number of tasks currently being executed by pool threads | Backed by `AtomicInteger` |
245-
| `executor.tasks.succeeded` | `Counter` | Total number of tasks that completed without throwing an exception | — |
246-
| `executor.tasks.failed` | `Counter` | Total number of tasks that completed by throwing an exception | — |
247-
| `executor.task.duration` | `Timer` | Wall-clock duration of each task execution | — |
242+
| Metric Name | Type | Description | Config |
243+
|----------------------------|-----------|--------------------------------------------------------------------|---------------------------|
244+
| `executor.active` | `Gauge` | Number of tasks currently being executed by pool threads | Backed by `AtomicInteger` |
245+
| `executor.tasks.succeeded` | `Counter` | Total number of tasks that completed without throwing an exception | — |
246+
| `executor.tasks.failed` | `Counter` | Total number of tasks that completed by throwing an exception | — |
247+
| `executor.task.duration` | `Timer` | Wall-clock duration of each task execution | — |
248248

249249
---
250250

@@ -258,13 +258,14 @@ Tags: `name` = `<executorName>`
258258

259259
## Exception Handling
260260

261-
| Exception | Condition |
262-
|---|---|
263-
| `MaximumAllowedMessageException` | A single message exceeds the 256KB SNS payload limit |
264-
| SDK exceptions (`AmazonServiceException` / `AwsServiceException`) | Service-side errors during `publishBatch` |
265-
| SDK exceptions (`AmazonClientException` / `AwsClientException`) | Client-side errors (network, serialization) |
261+
| Exception | Condition |
262+
|-------------------------------------------------------------------|------------------------------------------------------|
263+
| `MaximumAllowedMessageException` | A single message exceeds the 256KB SNS payload limit |
264+
| SDK exceptions (`AmazonServiceException` / `AwsServiceException`) | Service-side errors during `publishBatch` |
265+
| SDK exceptions (`AmazonClientException` / `AwsClientException`) | Client-side errors (network, serialization) |
266266

267267
Failed messages are delivered to the failure callback with:
268+
268269
- `messageId` — the original request ID
269270
- `code` — the error code
270271
- `message` — error description

‎README.md‎

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ In order to use Amazon SNS Java Messaging Lib within a Maven project, simply add
3434

3535
You can pull it from the central Maven repositories:
3636

37+
#### Maven
38+
3739
### For AWS SDK v1
3840

3941
```xml
@@ -336,39 +338,39 @@ When a `MeterRegistry` is provided via the builder, the library records these Mi
336338

337339
Tags: `topic` = `<topicArn>`
338340

339-
| Metric | Type | Description |
340-
|---|---|---|
341-
| `sns.publish.attempts` | Counter | Total PublishBatch attempts |
342-
| `sns.publish.success` | Counter | Successful messages |
343-
| `sns.publish.failure` | Counter | Failed messages (dynamic tags: `error_code`, `error_type`) |
344-
| `sns.publish.duration` | Timer | Publish latency (p50/p95/p99) |
345-
| `sns.publish.batch.size` | DistributionSummary | Messages per batch |
346-
| `sns.publish.inflight` | Gauge | In-flight publish batches |
341+
| Metric | Type | Description |
342+
|--------------------------|---------------------|------------------------------------------------------------|
343+
| `sns.publish.attempts` | Counter | Total PublishBatch attempts |
344+
| `sns.publish.success` | Counter | Successful messages |
345+
| `sns.publish.failure` | Counter | Failed messages (dynamic tags: `error_code`, `error_type`) |
346+
| `sns.publish.duration` | Timer | Publish latency (p50/p95/p99) |
347+
| `sns.publish.batch.size` | DistributionSummary | Messages per batch |
348+
| `sns.publish.inflight` | Gauge | In-flight publish batches |
347349

348350
### Blocking Queue
349351

350352
Tags: `name` = `<queueName>`
351353

352-
| Metric | Type | Description |
353-
|---|---|---|
354-
| `blocking.queue.puts.total` | Counter | Successful put operations |
355-
| `blocking.queue.puts.failed` | Counter | Put operations that threw an exception |
356-
| `blocking.queue.put.duration` | Timer | Put latency (percentile histogram) |
357-
| `blocking.queue.takes.total` | Counter | Successful take operations |
358-
| `blocking.queue.takes.failed` | Counter | Take operations that threw an exception |
359-
| `blocking.queue.take.duration` | Timer | Take latency (percentile histogram) |
360-
| `blocking.queue.size` | Gauge | Current queue depth |
354+
| Metric | Type | Description |
355+
|--------------------------------|---------|-----------------------------------------|
356+
| `blocking.queue.puts.total` | Counter | Successful put operations |
357+
| `blocking.queue.puts.failed` | Counter | Put operations that threw an exception |
358+
| `blocking.queue.put.duration` | Timer | Put latency (percentile histogram) |
359+
| `blocking.queue.takes.total` | Counter | Successful take operations |
360+
| `blocking.queue.takes.failed` | Counter | Take operations that threw an exception |
361+
| `blocking.queue.take.duration` | Timer | Take latency (percentile histogram) |
362+
| `blocking.queue.size` | Gauge | Current queue depth |
361363

362364
### Executor
363365

364366
Tags: `name` = `<executorName>`
365367

366-
| Metric | Type | Description |
367-
|---|---|---|
368-
| `executor.active` | Gauge | Tasks currently executing |
368+
| Metric | Type | Description |
369+
|----------------------------|---------|-----------------------------------|
370+
| `executor.active` | Gauge | Tasks currently executing |
369371
| `executor.tasks.succeeded` | Counter | Tasks completed without exception |
370-
| `executor.tasks.failed` | Counter | Tasks completed with exception |
371-
| `executor.task.duration` | Timer | Task wall-clock duration |
372+
| `executor.tasks.failed` | Counter | Tasks completed with exception |
373+
| `executor.task.duration` | Timer | Task wall-clock duration |
372374

373375
---
374376

@@ -382,7 +384,7 @@ We use [GitHub](https://github.com/mvallim/amazon-sns-java-messaging-lib) for ve
382384

383385
## Authors
384386

385-
* **Marcos Vallim** - *Founder, Author, Development, Test, Documentation* - [mvallim](https://github.com/mvallim)
387+
* **Marcos Vallim** - _Founder, Author, Development, Test, Documentation_ - [mvallim](https://github.com/mvallim)
386388

387389
See also the list of [contributors](CONTRIBUTORS.txt) who participated in this project.
388390

0 commit comments

Comments
 (0)