Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry) · Oppitunti

Manuaalisen instrumentoinnin parhaat käytännöt

Ymmärtäkää, milloin ja miten manuaalista instrumentointia käytetään observability-datan tarkkaan hallintaan. Oppikaa rikastamaan traceja mukautetuilla attribuuteilla.

Oppitunti 2/411 vaihetta

Manuaalisen instrumentoinnin parhaat käytännöt on ilmainen Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-kurssilla on yhteensä 4 oppituntia.

Manuaalisen instrumentoinnin johdanto

Tervetuloa! Tässä oppitunnissa perehdymme manuaaliseen instrumentointiin OpenTelemetryn avulla. Automaattinen instrumentointi sopii nopeisiin tuloksiin, mutta manuaalinen hallinta tarjoaa tarkkuutta.

Manuaalisen instrumentoinnin avulla voit tallentaa erittäin yksityiskohtaisia tietoja sovelluksesi sisäisistä toiminnoista. Tämä on tärkeää monimutkaisen liiketoimintalogiikan tai mukautettujen komponenttien virheenkorjauksessa.

Miksi manuaalinen eikä automaattinen instrumentointi?

Automaattinen instrumentointi kerää tietoja yleisistä kirjastoista ja kehyksistä automaattisesti. Se ei kuitenkaan voi tuntea sovelluksesi yksilöllistä logiikkaa.

Mukautettu logiikka: Instrumentoi tietyt funktiot tai koodilohkot.
Liiketoimintakonteksti: Lisää liiketoiminta-alueesi kannalta merkityksellisiä attribuutteja.
Hienojakoinen hallinta: Määritä spanien tarkat rajat ja suhteet.
Puuttuvan kattavuuden täydentäminen: Instrumentoi alueet, joihin automaattinen instrumentointi ei ulotu.

Ensimmäisen spanin luominen

Span edustaa yksittäistä operaatiota jäljityksen sisällä. Jos haluat luoda spanin manuaalisesti, tarvitset Tracer-olion, joka haetaan OpenTelemetry SDK:sta.

Uuden spanin käynnistäminen tapahtuu seuraavasti. Muista aina lopettaa spanit!

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.SpanBuilder;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ManualSpanDemo {
  public static void main(String[] args) {
    // Setup OpenTelemetry SDK (simplified for demo)
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    // Start a new span
    Span span = tracer.spanBuilder("MyCustomOperation").startSpan();

    try {
      System.out.println("Executing custom operation...");
      // Simulate work
      Thread.sleep(100);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      // Always end the span!
      span.end();
      System.out.println("Span ended.");
    }
  }
}

Spanien aktivointi Scopen avulla

Jotta span kuuluisi nykyiseen jäljityskontekstiin ja lapsispanit yhdistyisivät siihen automaattisesti, sen on oltava aktiivinen. Paras tapa hallita tätä on käyttää Scope-oliota try-with-resources-lauseen kanssa.

Näin span asetetaan automaattisesti aktiiviseksi ja lopetetaan lohkon päättyessä.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ActiveSpanDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span parentSpan = tracer.spanBuilder("ParentOperation").startSpan();
    try (Scope parentScope = parentSpan.makeCurrent()) { // Parent span is active
      System.out.println("Parent operation started.");

      Span childSpan = tracer.spanBuilder("ChildOperation").startSpan(); // Automatically links to parent
      try (Scope childScope = childSpan.makeCurrent()) {
        System.out.println("Child operation executing...");
        Thread.sleep(50);
      } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
      } finally {
        childSpan.end();
        System.out.println("Child operation ended.");
      }

      Thread.sleep(50);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      parentSpan.end();
      System.out.println("Parent operation ended.");
    }
  }
}

Mukautettujen attribuuttien lisääminen

Attribuutit ovat avain-arvo-pareja, jotka tarjoavat spanille kontekstitietoja. Ne ovat olennaisia, jotta jäljityksistä tulee haettavia ja ymmärrettäviä.

Voit lisätä attribuutteja spaniin käyttämällä span.setAttribute()-metodia. Käytä kuvaavia avaimia ja asiaankuuluvia arvoja.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanAttributesDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("ProcessOrder").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("Processing order...");
      // Add attributes for order details
      span.setAttribute("order.id", "XYZ789");
      span.setAttribute("customer.email", "user@example.com");
      span.setAttribute(AttributeKey.longKey("item.count"), 3L);

      Thread.sleep(150);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      span.end();
      System.out.println("Order processed. Span ended with attributes.");
    }
  }
}

Span-tapahtumien tallentaminen

Tapahtumat ovat spaniin liittyviä aikaleimattuja viestejä. Niitä voi käyttää merkittävien hetkien merkitsemiseen tai spanin elinkaaren aikana tapahtuvien tiettyjen toimien kirjaamiseen ilman uusien lapsispanien luomista.

Voit ajatella niitä jäljityksen sisäisinä minilokeina, jotka lisäävät yksityiskohtia tiettyyn operaatioon.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanEventsDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("UserLogin").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("User login initiated...");
      span.addEvent("AuthenticationStarted");

      Thread.sleep(80);
      // Add an event with attributes
      span.addEvent("DatabaseCheck", Attributes.of(
          AttributeKey.stringKey("db.query"), "SELECT * FROM users WHERE id=?"
      ));

      Thread.sleep(70);
      span.addEvent("AuthenticationSuccessful");

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      span.end();
      System.out.println("User login span ended with events.");
    }
  }
}

Virheiden käsittely spanien sisällä

On erittäin tärkeää merkitä spanit epäonnistuneiksi virheen sattuessa. Näin järjestelmän ongelmalliset operaatiot voidaan tunnistaa nopeasti.

Voit asettaa spanin tilaksi ERROR ja tallentaa epäonnistumisen aiheuttaneen poikkeuksen. Tämä tarjoaa runsaasti kontekstia virheenkorjausta varten.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanErrorDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("CriticalFunction").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("Executing critical function...");
      // Simulate an error condition
      if (Math.random() > 0.5) {
        throw new RuntimeException("Simulated critical failure!");
      }
      System.out.println("Critical function completed successfully.");

    } catch (Exception e) {
      System.out.println("Error caught: " + e.getMessage());
      span.setStatus(StatusCode.ERROR, "Function failed");
      span.recordException(e);
    } finally {
      span.end();
      System.out.println("Critical function span ended.");
    }
  }
}

Spanien parhaat käytännöt

Noudata seuraavia ohjeita, jotta saat manuaalisesta instrumentoinnista parhaan hyödyn:

Rakeisuus: Luo spanit merkityksellisille työyksiköille, älä jokaiselle koodiriville.
Merkitykselliset nimet: Käytä selkeitä nimiä, joiden kardinaliteetti on pieni (esim. user.login, db.query).
Monipuoliset attribuutit: Lisää attribuutteihin olennaista liiketoiminta- ja teknistä kontekstia.
Lopeta spanit aina: Käytä rakennetta try-with-resources tai kutsu eksplisiittisesti span.end() lohkossa finally.
Vältä liiallista instrumentointia: Liian monet spanit voivat aiheuttaa ylimääräistä kuormitusta. Keskity kriittisiin suorituspolkuihin.

Spanien eksplisiittinen linkittäminen

Vaikka makeCurrent() huolehtii useimmista isäntä–lapsi-linkityksistä, joskus spanit on linkitettävä eksplisiittisesti. Tämä on tavallista asynkronisissa tilanteissa tai integroitaisessa instrumentoimattomien järjestelmien kanssa.

Voit käyttää metodeja SpanBuilder.setParent() tai setNoParent() isäntä–lapsi-suhteen hallintaan.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.context.Context;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ExplicitLinkDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    // Imagine a span from an external system, represented by its context
    SpanContext externalContext = SpanContext.create(
        "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", // Trace ID
        "0000000000000001", // Span ID
        TraceFlags.getDefault(), TraceState.getDefault()
    );

    // Create a new span that links to this external context
    Span linkedSpan = tracer.spanBuilder("ProcessingExternalMessage")
        .setParent(Context.current().with(Span.wrap(externalContext))) // Link to external context
        .setSpanKind(SpanKind.CONSUMER) // Indicate it's a message consumer
        .startSpan();

    try {
      System.out.println("Processing message from external system...");
      linkedSpan.setAttribute("message.id", "MSG-123");
      Thread.sleep(100);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      linkedSpan.end();
      System.out.println("Linked span ended.");
    }
  }
}

Manuaalisen instrumentoinnin tarkistus

Olet toteuttamassa uutta ominaisuutta, joka laskee käyttäjän kanta-asiakaspisteet. Haluat instrumentoida tämän tietyn laskutoimituksen seurataksesi sen kestoa ja myönnettyjen pisteiden lopullista määrää. Mikä seuraavista on sopivin tapa tallentaa lopulliset pisteet manuaalisella OpenTelemetry-instrumentoinnilla?

Vastaa interaktiivisessa oppitunnissa

Kertaus: manuaalinen hallinta

Tässä oppitunnissa perehdyimme OpenTelemetryn manuaaliseen instrumentointiin. Opit seuraavat asiat:

Milloin manuaalinen instrumentointi kannattaa valita automaattisen instrumentoinnin sijaan tarkempaa hallintaa varten.
Miten spanit luodaan, aktivoidaan ja lopetetaan.
Miten attribuuteilla lisätään jäljitykseen monipuolista kontekstia.
Miten tapahtumilla merkitään spanin sisäisiä tiettyjä hetkiä.
Parhaat käytännöt virheiden käsittelyyn ja spanien eksplisiittiseen linkittämiseen.

Manuaalisen instrumentoinnin hallitseminen antaa ainutlaatuisen näkyvyyden sovelluksen erityiseen logiikkaan ja suorituskykyyn.

Aloita maksutta

Opi Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry) tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 12
Oppitunnit: 48

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Manuaalisen instrumentoinnin parhaat käytännöt” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppimispolun 3 oppituntia, myös oppitunnin “Manuaalisen instrumentoinnin parhaat käytännöt”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Manuaalisen instrumentoinnin parhaat käytännöt”?

Ymmärtäkää, milloin ja miten manuaalista instrumentointia käytetään observability-datan tarkkaan hallintaan. Oppikaa rikastamaan traceja mukautetuilla attribuuteilla. Harjoittelet Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”Manuaalisen instrumentoinnin parhaat käytännöt”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppitunnilla?

Kyllä. Jokainen Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

Automaattisen instrumentoinnin tekniikat
Manuaalisen instrumentoinnin parhaat käytännöt
Kontekstin välitys ja baggage
Spanien attribuutit, tapahtumat ja tila

← Takaisin: Järjestelmän observability: lokitus, metriikat ja jäljitys (ELK + OpenTelemetry)