Page Comparison

...

Viktigt att komma ihåg om man sätter om logg-kategorin är att man då även sätter om loggnivån på den konfigurerade loggkategorin till TRACE - om det inte görs kommer ingen trafikloggning att dyka upp i applikationens logg.

...

• null-värden exkluderas vid serialisering

• den JSON-data som genereras är indenterad, för ökad läsbarhet

• okända attribut ignoreras vid deserialisering

Vidare används Jackson för serialisering av objekt till YAML och tillbaka.

Inställningar
(Auto-konfigurationsklass: se.sundsvall.dept44.configuration.ObjectMapperConfiguration)

...

För att generera OpenAPI v3.x-specifikation och tillhandahålla ett Swagger UI används SpringDoc.

Minimal konfiguration i application.properties:

openapi.name=ett-api
openapi.title=Ett API
openapi.version=1.0

...

Inställningar

...

Viktigt att komma ihåg om man sätter om logg-kategorin är att man då även sätter om loggnivån på den konfigurerade loggkategorin till TRACE - om det inte görs kommer ingen trafikloggning att dyka upp i applikationens logg.

Anchor
jackson jackson

Jackson (serialisering/deserialisering av JSON och YAML)

Jackson används för serialisering av objekt till JSON och tillbaka - d.v.s. deserialisering av JSON till objekt. Konfigurationen som görs i ramverket innefattar bland annat:

• null-värden exkluderas vid serialisering

• den JSON-data som genereras är indenterad, för ökad läsbarhet

• okända attribut ignoreras vid deserialisering

Vidare används Jackson för serialisering av objekt till YAML och tillbaka.

Inställningar
(Auto-konfigurationsklass: se.sundsvall.dept44.configuration.openapi.OpenApiConfigurationObjectMapperConfiguration)

...

Inställning

...

Default-värde

...

Anchor
openapi openapi

...

...

OpenAPI

...

och Swagger UI

...

...

openapi.name (obligatorisk så länge openapi.enabled inte är false)

...

-

...

Namn som används för att generera URL till API-dokumentation. Får bara innehålla bokstäver, siffror, underscore och bindestreck

...

openapi.title (obligatorisk så länge openapi.enabled inte är false)

...

-

...

Titel som ska användas i OpenAPI-specifikationen

...

openapi.version (obligatorisk så länge openapi.enabled inte är false)

...

-

...

Versionsnummer som ska användas i OpenAPI-specifikationen

...

openapi.license.name

...

MIT

...

Namn på den licens som ska ingå i OpenAPI-specifikationen

...

openapi.license.url

...

https://opensource.org/licenses/MIT

...

Länk till den licens som ska ingå i OpenAPI-specifikationen

...

openapi.contact.name

...

-

...

Namnet på den kontakt som ska ingå i OpenAPI-specifikationen

...

openapi.contact.email

...

-

...

E-postadressen till den kontakt som ska ingå i OpenAPI-specifikationen

...

openapi.contact.url

...

-

...

URL för den kontakt som ska ingå i OpenAPI-specifikationen

...

openapi.security-scheme.oauth2.flow.tokenUrl

...

-

...

TODO

...

openapi.servers[n].url

...

-

...

TODO

...

openapi.servers[n].description

...

-

...

TODO

...

openapi.extensions.<extension>.... (Map)

...

-

...

Eventuella tillägg till OpenAPI-specifikationen

(se https://swagger.io/docs/specification/openapi-extensions/)

...

Dept44 erbjuder en möjlighet att addera “circuit-breakers” och “health-indicators” på en resurs (t.ex. en integrationsklient). Dept44 använder sig av Resilience4j för detta syfte. Detta ramverk möjliggör mycket mer funktionalitet än vad som beskrivs här. T.ex. RateLimiter, TimeLimiter, Retry, osv. För ytterligare info hänvisas till dokumentationen av Resilience4j. I detta avsnitt beskrivs enbart funktionalitet kopplad till s.k. “circuit-breakers” och “health-indicators”.

Genom att lägga till en “circuit-breaker” på en resurs får man automatiskt även en “health-indicator”. Dessa går hand i hand och återspeglar varandras status. Om en “circuit-breaker” öppnas kommer således motsvarande “health-indicator” att rapportera “DOWN”. Den “health-indicator” som skapas kommer att per automatik exponeras under sökvägen “/actuator/health” och kan plockas upp av t.ex. Spring boot admin om tjänsten anslutit sig mot en sådan server.

...

Code Block
@FeignClient(name = "MyFeignClient", url = "${integration.backend.url}", configuration = MyFeignClientConfiguration.class) @CircuitBreaker(name = "MyFeignClient") public interface MyFeignClient { ... }

[2] Skapar en “Circuit breaker” samt “Health indicator” med namnet “MyFeignClient”. Annoteringen kan placeras på både klass- och metodnivå. I detta exempel har den placerats på klassnivå och slår därför på alla metoder i klassen/interfacet.

Ovanstående är allt som krävs för att att skapa en “Circuit breaker” som bryter kretsen om resursen kastar en exception. Kretsen kommer vid dessa tillfällen att hållas öppen under en kort tidsperiod (default 60 sekunder), För att generera OpenAPI v3.x-specifikation och tillhandahålla ett Swagger UI används SpringDoc.

Minimal konfiguration i application.properties:

Code Block
openapi.name=ett-api openapi.title=Ett API openapi.version=1.0

OpenAPI-specifikationen exponeras på /api-docs. Som standard serveras OpenAPI-specifikationen som JSON, med kan även fås som YAML genom att sätta Accept-headern till application/yaml. YAML-representation av OpenAPI-specifikationen kan även nås via /api-docs.yaml.

Vidare läggs en endpoint /api-docs till i tjänstens Swagger UI som kommer att vara åtkomlig utan autentisering, där man kan hämta OpenAPI-specifikationen.

Se nedan för övriga valbara inställningar.

Inställningar

(Auto-konfiguration: se.sundsvall.dept44.configuration.openapi.OpenApiConfiguration)

Inställning	Default-värde	Beskrivning
openapi.enabled	true	Anger om OpenAPI-specifikation ska genereras och Swagger UI konfigureras
openapi.name (obligatorisk så länge openapi.enabled inte är false)	-	Namn som används för att generera URL till API-dokumentation. Får bara innehålla bokstäver, siffror, underscore och bindestreck
openapi.title (obligatorisk så länge openapi.enabled inte är false)	-	Titel som ska användas i OpenAPI-specifikationen
openapi.version (obligatorisk så länge openapi.enabled inte är false)	-	Versionsnummer som ska användas i OpenAPI-specifikationen
openapi.license.name	MIT	Namn på den licens som ska ingå i OpenAPI-specifikationen
openapi.license.url	https://opensource.org/licenses/MIT	Länk till den licens som ska ingå i OpenAPI-specifikationen
openapi.contact.name	-	Namnet på den kontakt som ska ingå i OpenAPI-specifikationen
openapi.contact.email	-	E-postadressen till den kontakt som ska ingå i OpenAPI-specifikationen
openapi.contact.url	-	URL för den kontakt som ska ingå i OpenAPI-specifikationen
openapi.security-scheme.oauth2.flow.tokenUrl	-	TODO
openapi.servers[n].url	-	TODO
openapi.servers[n].description	-	TODO
openapi.extensions.<extension>.... (Map)	-	Eventuella tillägg till OpenAPI-specifikationen (se https://swagger.io/docs/specification/openapi-extensions/)

Anchor
healthindicator healthindicator

Circuit breaker och health-indicator

Dept44 erbjuder en möjlighet att addera “circuit-breakers” och “health-indicators” på en resurs (t.ex. en integrationsklient). Dept44 använder sig av Resilience4j för detta syfte. Detta ramverk möjliggör mycket mer funktionalitet än vad som beskrivs här. T.ex. RateLimiter, TimeLimiter, Retry, osv. För ytterligare info hänvisas till dokumentationen av Resilience4j. I detta avsnitt beskrivs enbart funktionalitet kopplad till s.k. “circuit-breakers” och “health-indicators”.

Genom att lägga till en “circuit-breaker” på en resurs får man automatiskt även en “health-indicator”. Dessa går hand i hand och återspeglar varandras status. Om en “circuit-breaker” öppnas kommer således motsvarande “health-indicator” att rapportera “DOWN”. Den “health-indicator” som skapas kommer att per automatik exponeras under sökvägen “/actuator/health” och kan plockas upp av t.ex. Spring boot admin om tjänsten anslutit sig mot en sådan server.

Komma igång

Börja med att annotera din resurs.
Resursen brukar vanligtvis utgöras av en integrationsklient, databasklient, osv. Men det kan i princip vara vilken metod eller klass som helst som man vill övervaka med en “circuit-breaker” samt tillhörande “health-indicator”.

@FeignClient(name = "MyFeignClient", url = "${integration.backend.url}", configuration = MyFeignClientConfiguration.class)
@CircuitBreaker(name = "MyFeignClient")
public interface MyFeignClient {
...
}

[2] Skapar en “Circuit breaker” samt “Health indicator” med namnet “MyFeignClient”. Annoteringen kan placeras på både klass- och metodnivå. I detta exempel har den placerats på klassnivå och slår därför på alla metoder i klassen/interfacet.

Ovanstående är allt som krävs för att att skapa en “Circuit breaker” som bryter kretsen om resursen kastar en exception. Kretsen kommer vid dessa tillfällen att hållas öppen under en kort tidsperiod (default 60 sekunder), innan den övergår till ett “halvöppet” läge. I det “halvöppna” läget tillåts ett antal anrop (konfigurerbart) för att utvärdera resursens status. Under tiden som kretsen hålls öppen kommer den automatiskt registrerade health-indicatorn att visa “DOWN” för aktuell resurs. När resursen åter fungerar bra kommer kretsen att stängas helt och “health-indicatorn” visar “UP”.

...

Undantagna undantag

Det är viktigt att ha i åtanke att en “circuit-breaker” reagerar på alla typer av undantag (exceptions) som inte är exkluderade via propertyn ignoreExceptions. Av den anledningen är det viktigt att särskilja på exceptions som beror på rena indata-fel (som inte betyder att resursen har problem) och på de exceptions som tyder på att tjänsten har problem.

Ex:

...

att ha i åtanke att en “circuit-breaker” reagerar på alla typer av undantag (exceptions) som inte är exkluderade via propertyn ignoreExceptions. Av den anledningen är det viktigt att särskilja på exceptions som beror på rena indata-fel (som inte betyder att resursen har problem) och på de exceptions som tyder på att tjänsten har problem.

Ex:

resilience4j.circuitbreaker.instances.MyFeignClient.ignoreExceptions = javax.validation.ConstraintViolationException
resilience4j.circuitbreaker.configs.default.ignoreExceptions = javax.validation.ConstraintViolationException

[1] Sätter undantaget på en specifik circuitbreaker. Gör man på detta vis blir av någon anledning cirkuitbreakern oinitierad till dess att exception av annan typ kastats.
[2] Sätter undantaget på ALLA circuitbreakers i tjänsten. Gör man på detta vis initieras de (och blir synliga) i /acutators/health direkt efter första anropet.

I den Feign-klient som erbjuds av dept44 finns två subklasser av “Zalando Problem”:
se.sundsvall.dept44.exception.ClientProblem: Kastas när Feign-klienten tar emot ett svar med HTTP-status i 400-serien. Dessa brukar vanligtvis bero på fel orsakade av felaktiga ogiltiga parametrar och betyder vanligtvis inte att tjänsten ligger nere.
se.sundsvall.dept44.exception.ServerProblem: Kastas när Feign-klienten tar emot ett svar med HTTP-status i 500-serien. Dessa brukar vanligtvis bero på att tjänsten har problem.

...

{
  "status" : "DOWN",
  "components" : {
    "circuitBreakers" : {
      "status" : "DOWN",
      "details" : {
        "MyOtherFeignClient" : {
          "status" : "DOWN",
          "details" : {
            "failureRate" : "50.0%",
            "failureRateThreshold" : "50.0%",
            "slowCallRate" : "0.0%",
            "slowCallRateThreshold" : "100.0%",
            "bufferedCalls" : 10,
            "slowCalls" : 0,
            "slowFailedCalls" : 0,
            "failedCalls" : 5,
            "notPermittedCalls" : 11,
            "state" : "OPEN"
          }
        },
        "MyFeignClient" : {
          "status" : "UP",
          "details" : {
            "failureRate" : "-1.0%",
            "failureRateThreshold" : "50.0%",
            "slowCallRate" : "-1.0%",
            "slowCallRateThreshold" : "100.0%",
            "bufferedCalls" : 1,
            "slowCalls" : 0,
            "slowFailedCalls" : 0,
            "failedCalls" : 1,
            "notPermittedCalls" : 0,
            "state" : "CLOSED"
          }
        }
      }
    }
  }
}

{
  "circuitBreakerEvents" : [ {
    "circuitBreakerName" : "MyFeignClient",
    "type" : "IGNORED_ERROR",
    "creationTime" : "2022-06-14T10:45:00.967115+02:00[Europe/Stockholm]",
    "errorMessage" : "javax.validation.Exception: test.uuid: not a valid UUID",
    "durationInMs" : 16
  }, {
    "circuitBreakerName" : "MyFeignClient",
    "type" : "IGNORED_ERROR",
    "creationTime" : "2022-06-14T10:46:08.104328300+02:00[Europe/Stockholm]",
    "errorMessage" : "about:blank{502, Bad Gateway, POB error: {detail=, status=401 Unauthorized, title=Authorization has been denied for this request.}}",
    "durationInMs" : 289
  } ] 
}

{
  "circuitBreakers" : [ "MyFeignClient", "MyOtherFeignClient" ]
}

...