{"id":30715424,"url":"https://github.com/superstreamlabs/superstream-clients-java","last_synced_at":"2025-09-03T06:08:25.344Z","repository":{"id":289003270,"uuid":"969799137","full_name":"superstreamlabs/superstream-clients-java","owner":"superstreamlabs","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-20T07:48:14.000Z","size":439,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-20T09:30:56.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/superstreamlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-21T00:22:48.000Z","updated_at":"2025-07-20T07:46:20.000Z","dependencies_parsed_at":"2025-06-11T11:51:31.104Z","dependency_job_id":"b8a6ae9e-bf8b-416d-b1eb-232d6a5f1c8e","html_url":"https://github.com/superstreamlabs/superstream-clients-java","commit_stats":null,"previous_names":["superstreamlabs/superstream-clients-parent","superstreamlabs/superstream-clients-java"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/superstreamlabs/superstream-clients-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstreamlabs%2Fsuperstream-clients-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstreamlabs%2Fsuperstream-clients-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstreamlabs%2Fsuperstream-clients-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstreamlabs%2Fsuperstream-clients-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superstreamlabs","download_url":"https://codeload.github.com/superstreamlabs/superstream-clients-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstreamlabs%2Fsuperstream-clients-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273398097,"owners_count":25098301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T06:08:20.199Z","updated_at":"2025-09-03T06:08:25.331Z","avatar_url":"https://github.com/superstreamlabs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://github.com/user-attachments/assets/35899c78-24eb-4507-97ed-e87e84c49fea#gh-dark-mode-only\" width=\"300\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/8a7bca49-c362-4a8c-945e-a331fb26d8eb#gh-light-mode-only\" width=\"300\"\u003e\n\n\u003c/div\u003e\n\n# Superstream Client For Java\n\nA Java library for automatically optimizing Kafka producer configurations based on topic-specific recommendations.\n\n## Overview\n\nSuperstream Clients works as a Java agent that intercepts Kafka producer creation and applies optimized configurations without requiring any code changes in your application. It dynamically retrieves optimization recommendations from Superstream and applies them based on impact analysis.\n\n## Supported Libraries\n\nWorks with any Java library that depends on `kafka-clients`, including:\n\n- Apache Kafka Clients\n- Spring Kafka\n- Alpakka Kafka (Akka Kafka)\n- Pekko Kafka (Apache Pekko)\n- Kafka Streams\n- Kafka Connect\n- Any custom wrapper around the Kafka Java client\n\n## Features\n\n- **Zero-code integration**: No code changes required in your application\n- **Dynamic configuration**: Applies optimized settings based on topic-specific recommendations\n- **Intelligent optimization**: Identifies the most impactful topics to optimize\n- **Graceful fallback**: Falls back to default settings if optimization fails\n\n## Java Version Compatibility\n\nThe library fully supports Java versions 11 through 21.\n\n## Important: Producer Configuration Requirements\n\nWhen initializing your Kafka producers, please ensure you pass the configuration as a mutable object. The Superstream library needs to modify the producer configuration to apply optimizations. The following initialization patterns are supported:\n\n✅ **Supported (Recommended)**:\n```java\n// Using Properties (recommended)\nProperties props = new Properties();\nprops.put(\"bootstrap.servers\", \"localhost:9092\");\n// ... other properties ...\nKafkaProducer\u003cString, String\u003e producer = new KafkaProducer\u003c\u003e(props);\n\n// Using a regular HashMap\nMap\u003cString, Object\u003e config = new HashMap\u003c\u003e();\nconfig.put(\"bootstrap.servers\", \"localhost:9092\");\n// ... other properties ...\nKafkaProducer\u003cString, String\u003e producer = new KafkaProducer\u003c\u003e(config);\n\n// Using Spring's @Value annotations and configuration loading\n@Configuration\npublic class KafkaConfig {\n    @Value(\"${spring.kafka.bootstrap-servers}\")\n    private String bootstrapServers;\n    // ... other properties ...\n\n    @Bean\n    public ProducerFactory\u003cString, String\u003e producerFactory() {\n        Map\u003cString, Object\u003e configProps = new HashMap\u003c\u003e();\n        configProps.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);\n        // ... other properties ...\n        return new DefaultKafkaProducerFactory\u003c\u003e(configProps);\n    }\n}\n```\n\n❌ **Not Supported**:\n```java\n// Using Collections.unmodifiableMap\nMap\u003cString, Object\u003e config = Collections.unmodifiableMap(new HashMap\u003c\u003e());\nKafkaProducer\u003cString, String\u003e producer = new KafkaProducer\u003c\u003e(config);\n\n// Using Map.of() (creates unmodifiable map)\nKafkaProducer\u003cString, String\u003e producer = new KafkaProducer\u003c\u003e(\n    Map.of(\"bootstrap.servers\", \"localhost:9092\")\n);\n\n// Using KafkaTemplate's getProducerFactory().getConfigurationProperties()\n// which returns an unmodifiable map\nKafkaTemplate\u003cString, String\u003e template = new KafkaTemplate\u003c\u003e(producerFactory);\nKafkaProducer\u003cString, String\u003e producer = new KafkaProducer\u003c\u003e(\n    template.getProducerFactory().getConfigurationProperties()\n);\n```\n\n### Spring Applications\nSpring applications that use `@Value` annotations and Spring's configuration loading (like `application.yml` or `application.properties`) are fully supported. The Superstream library will be able to modify the configuration when it's loaded into a mutable `Map` or `Properties` object in your Spring configuration class.\n\nExample of supported Spring configuration:\n```yaml\n# application.yml\nspring:\n  kafka:\n    producer:\n      properties:\n        compression.type: snappy\n        batch.size: 16384\n        linger.ms: 1\n```\n\n```java\n@Configuration\npublic class KafkaConfig {\n    @Value(\"${spring.kafka.producer.properties.compression.type}\")\n    private String compressionType;\n    \n    @Bean\n    public ProducerFactory\u003cString, String\u003e producerFactory() {\n        Map\u003cString, Object\u003e configProps = new HashMap\u003c\u003e();\n        configProps.put(ProducerConfig.COMPRESSION_TYPE_CONFIG, compressionType);\n        return new DefaultKafkaProducerFactory\u003c\u003e(configProps);\n    }\n}\n```\n\n### Pekko/Akka Kafka Applications\nPekko and Akka Kafka applications typically use immutable configuration maps internally, which prevents Superstream from applying optimizations. To enable Superstream optimizations with Pekko/Akka, you need to create the KafkaProducer manually with a mutable configuration.\n\n✅ **Superstream-optimized pattern**:\n```java\n// Add these lines to create a mutable producer\nMap\u003cString, Object\u003e configProps = new HashMap\u003c\u003e();\nconfigProps.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, \"localhost:9092\");\nconfigProps.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());\nconfigProps.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());\n\norg.apache.kafka.clients.producer.Producer\u003cString, String\u003e kafkaProducer = new KafkaProducer\u003c\u003e(configProps);\n\nProducerSettings\u003cString, String\u003e producerSettings = ProducerSettings\n    .create(system, new StringSerializer(), new StringSerializer())\n    .withProducer(kafkaProducer);\n\nSource.single(ProducerMessage.single(record))\n    .via(Producer.flexiFlow(producerSettings))\n    .runWith(Sink.ignore, system);\n```\n\n❌ **Native Pekko/Akka pattern (optimizations won't be applied)**:\n```java\nProducerSettings\u003cString, String\u003e producerSettings = ProducerSettings\n    .create(system, new StringSerializer(), new StringSerializer())\n    .withBootstrapServers(\"localhost:9092\");\n\nSource.single(ProducerMessage.single(record))\n    .via(Producer.flexiFlow(producerSettings))\n    .runWith(Sink.ignore, system);\n```\n\n### Why This Matters\nThe Superstream library needs to modify your producer's configuration to apply optimizations based on your cluster's characteristics. This includes adjusting settings like compression, batch size, and other performance parameters. When the configuration is immutable, these optimizations cannot be applied.\n\n## Installation\n\n*Superstream package*: https://central.sonatype.com/artifact/ai.superstream/superstream-clients-java/overview\n\n### Step 1: Add Superstream Jar to your application\n\n#### Download from GitHub\n\nhttps://github.com/superstreamlabs/superstream-clients-java/releases\n\n#### Available also in Maven Central\n\nhttps://central.sonatype.com/artifact/ai.superstream/superstream-clients\n\n### Step 2: Run\n\nAdd the Java agent to your application's startup command:\n\n```bash\njava -javaagent:/path/to/superstream-clients-1.0.16.jar -jar your-application.jar\n```\n\n### Docker Integration\n\nWhen using Superstream Clients with containerized applications, include the agent in your Dockerfile:\n\n```dockerfile\nFROM openjdk:11-jre\n\nWORKDIR /app\n\n# Copy your application\nCOPY target/your-application.jar app.jar\n\n# Copy the Superstream agent\nCOPY path/to/superstream-clients-1.0.16.jar superstream-agent.jar\n\n# Run with the Java agent\nENTRYPOINT [\"java\", \"-javaagent:/app/superstream-agent.jar\", \"-jar\", \"/app/app.jar\"]\n```\n\nAlternatively, you can use a multi-stage build to download the agent from Maven Central:\n\n\n### Required Environment Variables\n\n- `SUPERSTREAM_TOPICS_LIST`: Comma-separated list of topics your application produces to\n\n### Optional Environment Variables\n\n- `SUPERSTREAM_LATENCY_SENSITIVE`: Set to \"true\" to prevent any modification to linger.ms values\n- `SUPERSTREAM_DISABLED`: Set to \"true\" to disable optimization\n- `SUPERSTREAM_DEBUG`: Set to \"true\" to enable debug logs\n\nExample:\n```bash\nexport SUPERSTREAM_TOPICS_LIST=orders,payments,user-events\nexport SUPERSTREAM_LATENCY_SENSITIVE=true\n```\n\n## Prerequisites\n\n- Java 11 or higher\n- Kafka cluster that is connected to the Superstream's console\n- Read and write permissions to the `superstream.*` topics\n\n## License\n\nThis project is licensed under the Apache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstreamlabs%2Fsuperstream-clients-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperstreamlabs%2Fsuperstream-clients-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstreamlabs%2Fsuperstream-clients-java/lists"}