Azure Cosmos Test client library for Java - version 1.0.0-beta.9

Library containing core fault injection classes used to test Azure Cosmos DB SDK libraries.

Getting started

Include the package

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos-test</artifactId>
  <version>1.0.0-beta.9</version>
</dependency>

Prerequisites

• Java Development Kit (JDK) with version 8 or above
• An active Azure account. If you don't have one, you can sign up for a free account. Alternatively, you can use the Azure Cosmos DB Emulator for development and testing. As emulator HTTPS certificate is self-signed, you need to import its certificate to java trusted cert store as explained here
• (Optional) SLF4J is a logging facade.
• (Optional) SLF4J binding is used to associate a specific logging framework with SLF4J.
• (Optional) Maven

SLF4J is only needed if you plan to use logging, please also download an SLF4J binding which will link the SLF4J API with the logging implementation of your choice. See the SLF4J user manual for more information.

The SDK provides Reactor Core-based async APIs. You can read more about Reactor Core and Flux/Mono types here

Key concepts

The Azure Cosmos Test library can be used to inject failure into Azure Cosmos SDK for Java.

Examples

The following section provides several code snippets covering how to create some of the most common failure injection scenario, including:

• High Channel Acquisition Scenario
• Broken Connection Scenario
• Server Return Gone Scenario
• Random Connection Close Scenario

High Channel Acquisition Scenario

FaultInjectionRule serverConnectionDelayRule =
    new FaultInjectionRuleBuilder("<YOUR RULE ID>")
        .condition(
            new FaultInjectionConditionBuilder()
                .operationType(FaultInjectionOperationType.CREATE_ITEM)
                .build()
        )
        .result(
            FaultInjectionResultBuilders
                .getResultBuilder(FaultInjectionServerErrorType.CONNECTION_DELAY)
                .delay(Duration.ofSeconds(6)) // default connection timeout is 5s
                .times(1)
                .build()
        )
        .duration(Duration.ofMinutes(5))
        .build();

CosmosFaultInjectionHelper.configureFaultInjectionRules(container, Arrays.asList(serverConnectionDelayRule)).block();

Broken Connection Scenario

FaultInjectionRule timeoutRule =
    new FaultInjectionRuleBuilder("<YOUR RULE ID>")
        .condition(
            new FaultInjectionConditionBuilder()
                .operationType(FaultInjectionOperationType.READ_ITEM)
                .build()
        )
        .result(
            FaultInjectionResultBuilders
                .getResultBuilder(FaultInjectionServerErrorType.RESPONSE_DELAY)
                .times(1)
                .delay(Duration.ofSeconds(6)) // the default time out is 5s
                .build()
        )
        .duration(Duration.ofMinutes(5))
        .build();

CosmosFaultInjectionHelper.configureFaultInjectionRules(container, Arrays.asList(timeoutRule)).block();

Server Return Gone Scenario

FaultInjectionRule serverErrorRule =
    new FaultInjectionRuleBuilder("<YOUR RULE ID>")
        .condition(
            new FaultInjectionConditionBuilder()
                .operationType(FaultInjectionOperationType.READ_ITEM)
                .build()
        )
        .result(
            FaultInjectionResultBuilders
                .getResultBuilder(FaultInjectionServerErrorType.GONE)
                .times(1)
                .build()
        )
        .duration(Duration.ofMinutes(5))
        .build();

CosmosFaultInjectionHelper.configureFaultInjectionRules(container, Arrays.asList(serverErrorRule)).block();

Random Connection Close Scenario

FaultInjectionRule connectionErrorRule =
    new FaultInjectionRuleBuilder("<YOUR RULE ID>")
        .condition(
            new FaultInjectionConditionBuilder()
                .operationType(FaultInjectionOperationType.CREATE_ITEM)
                .endpoints(new FaultInjectionEndpointBuilder(FeedRange.forLogicalPartition(new PartitionKey("<YOUR PARTITION KEY>"))).build())
                .build()
        )
        .result(
            FaultInjectionResultBuilders
                .getResultBuilder(FaultInjectionConnectionErrorType.CONNECTION_CLOSE)
                .interval(Duration.ofSeconds(1))
                .threshold(1.0)
                .build()
        )
        .duration(Duration.ofSeconds(2))
        .build();

CosmosFaultInjectionHelper.configureFaultInjectionRules(container, Arrays.asList(connectionErrorRule)).block();

Troubleshooting

General

Azure Cosmos DB is a fast and flexible distributed database that scales seamlessly with guaranteed latency and throughput. You do not have to make major architecture changes or write complex code to scale your database with Azure Cosmos DB. Scaling up and down is as easy as making a single API call or SDK method call. However, because Azure Cosmos DB is accessed via network calls there are client-side optimizations you can make to achieve peak performance when using Azure Cosmos DB Java SDK v4.

• Performance guide covers these client-side optimizations.

• Troubleshooting Guide covers common issues, workarounds, diagnostic steps, and tools when you use Azure Cosmos DB Java SDK v4 with Azure Cosmos DB SQL API accounts.

Enable Client Logging

Next steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.