Skip to content

Commit

Permalink
Add doc for observability
Browse files Browse the repository at this point in the history
  • Loading branch information
@aureamunoz
aureamunoz committed Oct 11, 2023
1 parent 0cc94ba commit 9826df3
Show file tree
Hide file tree
Showing 16 changed files with 295 additions and 37 deletions.
6 changes: 3 additions & 3 deletions api/src/main/java/io/smallrye/stork/api/Service.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

import io.smallrye.mutiny.Uni;
import io.smallrye.stork.api.observability.ObservationCollector;
import io.smallrye.stork.api.observability.StorkObservationPoints;
import io.smallrye.stork.api.observability.StorkObservation;

/**
* Represents a <em>Service</em>.
Expand Down Expand Up @@ -62,7 +62,7 @@ public Service(String serviceName,
* a service instance capable of handling a call
*/
public Uni<ServiceInstance> selectInstance() {
StorkObservationPoints observationPoints = observations.create(serviceName, serviceDiscoveryType,
StorkObservation observationPoints = observations.create(serviceName, serviceDiscoveryType,
serviceSelectionType);
return serviceDiscovery.getServiceInstances()
.onItemOrFailure().invoke((list, failure) -> {
Expand Down Expand Up @@ -109,7 +109,7 @@ public ServiceInstance selectInstance(Collection<ServiceInstance> instances) {
* @see LoadBalancer#requiresStrictRecording()
*/
public Uni<ServiceInstance> selectInstanceAndRecordStart(boolean measureTime) {
StorkObservationPoints observationPoints = observations.create(serviceName, serviceDiscoveryType,
StorkObservation observationPoints = observations.create(serviceName, serviceDiscoveryType,
serviceSelectionType);
return serviceDiscovery.getServiceInstances().onItemOrFailure().invoke((list, failure) -> {
if (failure != null) {
Expand Down
4 changes: 2 additions & 2 deletions api/src/main/java/io/smallrye/stork/api/observability/NoopObservationCollector.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ public class NoopObservationCollector implements ObservationCollector {
// NOOP
};

public static final StorkObservationPoints NOOP_STORK_EVENT = new StorkObservationPoints(
public static final StorkObservation NOOP_STORK_EVENT = new StorkObservation(
null, null,
null, NOOP_HANDLER) {
@Override
Expand All @@ -35,7 +35,7 @@ public void onServiceSelectionFailure(Throwable throwable) {
};

@Override
public StorkObservationPoints create(String serviceName, String serviceDiscoveryType,
public StorkObservation create(String serviceName, String serviceDiscoveryType,
String serviceSelectionType) {
return NOOP_STORK_EVENT;
}
Expand Down
2 changes: 1 addition & 1 deletion api/src/main/java/io/smallrye/stork/api/observability/ObservationCollector.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@

public interface ObservationCollector {

StorkObservationPoints create(String serviceName, String serviceDiscoveryType, String serviceSelectionType);
StorkObservation create(String serviceName, String serviceDiscoveryType, String serviceSelectionType);

}
Empty file removed api/src/main/java/io/smallrye/stork/api/observability/ObservationPoints.java
View file
Empty file.
2 changes: 1 addition & 1 deletion api/src/main/java/io/smallrye/stork/api/observability/StorkEventHandler.java
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
package io.smallrye.stork.api.observability;

public interface StorkEventHandler {
void complete(StorkObservationPoints event);
void complete(StorkObservation event);
}
8 changes: 2 additions & 6 deletions ...observability/StorkObservationPoints.java → ...k/api/observability/StorkObservation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

import io.smallrye.stork.api.ServiceInstance;

public class StorkObservationPoints {
public class StorkObservation {
// Handler / Reporter
private final StorkEventHandler handler;

Expand All @@ -30,7 +30,7 @@ public class StorkObservationPoints {
private volatile boolean serviceDiscoverySuccessful = false;
private volatile Throwable failure;

public StorkObservationPoints(String serviceName, String serviceDiscoveryType, String serviceSelectionType,
public StorkObservation(String serviceName, String serviceDiscoveryType, String serviceSelectionType,
StorkEventHandler handler) {
this.handler = handler;
this.serviceName = serviceName;
Expand Down Expand Up @@ -111,10 +111,6 @@ public Throwable failure() {
return failure;
}

public long getSelectedInstanceId() {
return selectedInstanceId;
}

public boolean isServiceDiscoverySuccessful() {
return serviceDiscoverySuccessful;
}
Expand Down
9 changes: 5 additions & 4 deletions core/src/test/java/io/smallrye/stork/FakeObservationCollector.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,20 @@

import io.smallrye.stork.api.observability.ObservationCollector;
import io.smallrye.stork.api.observability.StorkEventHandler;
import io.smallrye.stork.api.observability.StorkObservationPoints;
import io.smallrye.stork.api.observability.StorkObservation;

public class FakeObservationCollector implements ObservationCollector {

private static final StorkEventHandler FAKE_HANDLER = ev -> {
// FAKE
};
public static StorkObservationPoints FAKE_STORK_EVENT;

public static StorkObservation FAKE_STORK_EVENT;

@Override
public StorkObservationPoints create(String serviceName, String serviceDiscoveryType,
public StorkObservation create(String serviceName, String serviceDiscoveryType,
String serviceSelectionType) {
FAKE_STORK_EVENT = new StorkObservationPoints(
FAKE_STORK_EVENT = new StorkObservation(
serviceName, serviceDiscoveryType, serviceSelectionType,
FAKE_HANDLER);
return FAKE_STORK_EVENT;
Expand Down
33 changes: 13 additions & 20 deletions core/src/test/java/io/smallrye/stork/ObservationTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
import io.smallrye.stork.api.NoServiceInstanceFoundException;
import io.smallrye.stork.api.Service;
import io.smallrye.stork.api.ServiceInstance;
import io.smallrye.stork.api.observability.StorkObservationPoints;
import io.smallrye.stork.api.observability.StorkObservation;
import io.smallrye.stork.integration.ObservableStorkInfrastructure;
import io.smallrye.stork.spi.config.ConfigProvider;

Expand Down Expand Up @@ -60,12 +60,11 @@ void shouldGetMetricsWhenSelectingInstanceHappyPath() {

//One instance is found and metrics are also gathered accordingly
assertThat(service.getObservations()).isNotNull();
StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isNull();
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(1);
assertThat(metrics.getSelectedInstanceId()).isNotNegative();
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand All @@ -74,7 +73,7 @@ void shouldGetMetricsWhenSelectingInstanceHappyPath() {

}

private static void assertDurations(StorkObservationPoints metrics) {
private static void assertDurations(StorkObservation metrics) {
Duration overallDuration = metrics.getOverallDuration();
Duration serviceDiscoveryDuration = metrics.getServiceDiscoveryDuration();
Duration serviceSelectionDuration = metrics.getServiceSelectionDuration();
Expand Down Expand Up @@ -108,12 +107,11 @@ void shouldGetMetricsAfterSelectingInstanceWhenServiceDiscoveryFails() {
assertThat(exception.getMessage()).isEqualTo("Service Discovery induced failure");
assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(-1);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isFalse();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("mock");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand Down Expand Up @@ -144,12 +142,11 @@ void shouldGetMetricsWhenSelectingInstanceFails() {
assertThat(exception.getMessage()).isEqualTo("Load Balancer induced failure");
assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(1);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("fake-selector");
Expand All @@ -158,7 +155,7 @@ void shouldGetMetricsWhenSelectingInstanceFails() {
}

@Test
void shouldGetMetricsAfterSelectingInstanceWhenWhenNoServicesDiscovered() {
void shouldGetMetricsAfterSelectingInstanceWhenNoServicesDiscovered() {
TestEnv.configurations.add(new FakeServiceConfig("my-service",
FAKE_SERVICE_DISCOVERY_CONFIG, null, null));

Expand All @@ -172,13 +169,12 @@ void shouldGetMetricsAfterSelectingInstanceWhenWhenNoServicesDiscovered() {

assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isNotNull();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(0);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand All @@ -201,13 +197,12 @@ void shouldGetMetricsWhenSelectingInstanceWithRecordAndStartHappyPath() {
assertThat(service.selectInstanceAndRecordStart(true).await().indefinitely()).isEqualTo(instance);
assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isNull();
assertThat(metrics.getOverallDuration()).isNotNull();
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(1);
assertThat(metrics.getSelectedInstanceId()).isNotNegative();
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand Down Expand Up @@ -236,12 +231,11 @@ void shouldGetMetricsAfterSelectingInstanceWithMonitoringWhenServiceDiscoveryFai
assertThat(exception.getMessage()).isEqualTo("Service Discovery induced failure");
assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(-1);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isFalse();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("mock");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand Down Expand Up @@ -272,12 +266,11 @@ void shouldGetMetricsWhenSelectingInstanceWithMonitoringFails() {
assertThat(exception.getMessage()).isEqualTo("Load Balancer induced failure");
assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(1);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("fake-selector");
Expand All @@ -300,13 +293,12 @@ void shouldGetMetricsAfterSelectingInstanceWithMonitoringWhenWhenNoServicesDisco

assertThat(service.getObservations()).isNotNull();

StorkObservationPoints metrics = FakeObservationCollector.FAKE_STORK_EVENT;
StorkObservation metrics = FakeObservationCollector.FAKE_STORK_EVENT;
assertThat(metrics.getServiceName()).isEqualTo("my-service");
assertThat(metrics.isDone()).isTrue();
assertThat(metrics.failure()).isNotNull();
assertThat(metrics.failure()).isEqualTo(exception);
assertThat(metrics.getDiscoveredInstancesCount()).isEqualTo(0);
assertThat(metrics.getSelectedInstanceId()).isEqualTo(-1);
assertThat(metrics.isServiceDiscoverySuccessful()).isTrue();
assertThat(metrics.getServiceDiscoveryType()).isEqualTo("fake");
assertThat(metrics.getServiceSelectionType()).isEqualTo("round-robin");
Expand All @@ -315,7 +307,8 @@ void shouldGetMetricsAfterSelectingInstanceWithMonitoringWhenWhenNoServicesDisco
}

private static Stork getNewObservableStork() {
return new Stork(new ObservableStorkInfrastructure(new FakeObservationCollector()));
Stork.initialize(new ObservableStorkInfrastructure(new FakeObservationCollector()));
return Stork.getInstance();
}

}
24 changes: 24 additions & 0 deletions docs/docs/diagrams/observability_sequence.puml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
@startuml

!include diagrams/includes/themes/light.puml

skinparam sequenceMessageAlign center
autonumber "<b>(0)"


participant Application
participant ObservableStorkInfrastructure
participant ObservationCollector
participant Stork
participant Service

Application -> ObservableStorkInfrastructure : instantiates
ObservableStorkInfrastructure -> ObservationCollector : instantiates
ObservationCollector -> ObservableStorkInfrastructure: ObservationCollector
ObservableStorkInfrastructure -> Application: ObservableStorkInfrastructure

... ...

Application -> Stork : initialize(observableInfrastructure)
Stork -> Service : instantiates (..., ObservationCollector, ...)
@enduml
37 changes: 37 additions & 0 deletions docs/docs/diagrams/observation_sequence.puml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
@startuml

!include diagrams/includes/themes/light.puml

skinparam sequenceMessageAlign center
autonumber "<b>(0)"


participant Service
participant ObservationCollector
participant StorkObservation
participant StorkEventHandler

Service -> ObservationCollector : create("serviceName", sd type, ss type)
ObservationCollector -> StorkObservation : instantiates
StorkObservation -> StorkObservation: Registers start time
ObservationCollector -> Service : StorkObservation

... ...

Service -> StorkObservation : onServiceDiscoverySuccess(List<ServiceInstance>)
StorkObservation -> StorkObservation : Registers end service\ndiscovery time.\nRegisters instances count\n
... ...

Service -> StorkObservation : onServiceDiscoveryFailure(Throwable)
StorkObservation -> StorkObservation : Registers end service\ndiscovery time.\nRegisters failure cause\n
... ...

Service -> StorkObservation : onServiceSelectionSuccess(instanceId)
StorkObservation -> StorkObservation : Registers end service\nselection time.\nRegisters instance id\nRegisters overall duration\n
StorkObservation -> StorkEventHandler: complete(this)
... ...

Service -> StorkObservation : onServiceSelectionFailure(Throwable))
StorkObservation -> StorkObservation : Registers overall duration.\nRegisters failure cause\n
StorkObservation -> StorkEventHandler: complete(this)
@enduml
Loading

0 comments on commit 9826df3

Please sign in to comment.