Émettre des événements de trace en Scala¶

Ajout d’une prise en charge de l’API de télémétrie¶

Pour utiliser les méthodes Telemetry, vous devez mettre la bibliothèque de télémétrie Snowflake, qui est incluse dans Snowflake, à la disposition de votre code de gestionnaire.

• Dans la clause PACKAGES de votre instruction CREATE PROCEDURE ou CREATE FUNCTION, incluez le paquet com.snowflake:telemetry. La clause PACKAGES rend l’API de télémétrie Snowflake incluse disponible pour votre code.

  Le code de l’exemple suivant utilise la clause PACKAGES pour référencer la bibliothèque de télémétrie ainsi que la bibliothèque Snowpark (qui est requise pour les procédures stockées écrites en Scala - pour plus d’informations, voir Écriture de procédures stockées en Scala).

  CREATE OR REPLACE PROCEDURE MYPROC(...)
    RETURNS ...
    LANGUAGE SCALA
    ...
    PACKAGES = ('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
    ...
  

  Copy

• Importez le paquet com.snowflake.telemetry dans le code de votre gestionnaire.

  import com.snowflake.telemetry.Telemetry
  

  Copy

Ajout d’événements de trace¶

Vous pouvez ajouter des événements de trace en appelant la méthode Telemetry.addEvent et en indiquant le nom de l’événement. Il est également possible d’associer des attributs (paires clé-valeur) à un événement.

La méthode addEvent a les signatures suivantes :

public static void addEvent(String name)
public static void addEvent(String name, Attributes attributes)

Le code de l’exemple suivant ajoute un événement appelé testEvent et lui associe deux attributs : key et result.

// Adding an event without attributes.
Telemetry.addEvent("testEvent");

// Adding an event with attributes.
Attributes eventAttributes = Attributes.of(
  AttributeKey.stringKey("key"), "run",
  AttributeKey.longKey("result"), Long.valueOf(123))
Telemetry.addEvent("testEventWithAttributes", eventAttributes)

L’ajout de ces événements donne lieu à deux lignes dans la table des événements, chacune avec une valeur différente dans la colonne RECORD :

{
  "name": "testEvent"
}

{
  "name": "testEventWithAttributes"
}

La ligne d’événement testEventWithAttributes comprend les attributs suivants dans la colonne RECORD_ATTRIBUTES de la ligne :

{
  "key": "run",
  "result": 123
}

Ajout d’attributs de span¶

Vous pouvez définir des attributs (paires clé-valeur) associés aux spans en appelant la méthode Telemetry.setSpanAttribute.

La méthode setSpanAttribute a les signatures suivantes :

public static void setSpanAttribute(String key, boolean value)
public static void setSpanAttribute(String key, long value)
public static void setSpanAttribute(String key, double value)
public static void setSpanAttribute(String key, String value)

Pour plus de détails sur les spans, voir Comment Snowflake représente les événements de trace.

Le code de l’exemple suivant crée quatre attributs et définit leurs valeurs :

// Setting span attributes.
Telemetry.setSpanAttribute("example.boolean", true)
Telemetry.setSpanAttribute("example.long", 2L)
Telemetry.setSpanAttribute("example.double", 2.5)
Telemetry.setSpanAttribute("example.string", "testAttribute")

La définition de ces attributs se traduit par les éléments suivants dans la colonne RECORD_ATTRIBUTES de la table des événements :

{
  "example.boolean": true,
  "example.long": 2,
  "example.double": 2.5,
  "example.string": "testAttribute"
}

Exemples¶

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS STRING
LANGUAGE SCALA
RUNTIME_VERSION = '2.12'
PACKAGES=('com.snowflake:snowpark:latest', 'com.snowflake:telemetry:latest')
HANDLER = 'ProcedureHandler.run'
AS
$$
import com.snowflake.snowpark_java.Session;
import com.snowflake.telemetry.Telemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;

class ProcedureHandler {

  def run(session: Session): String = {

    // Set span attribute.
    Telemetry.setSpanAttribute("example.proc.do_tracing", "begin");

    // Add an event without attributes.
    Telemetry.addEvent("run_method_start");

    // Add an event with attributes.
    val eventAttributes: Attributes = Attributes.of(
      AttributeKey.stringKey("example.method.name"), "run")
    Telemetry.addEvent("event_with_attributes", eventAttributes);

    // Set span attribute.
    Telemetry.setSpanAttribute("example.proc.do_tracing", "complete");

    return "SUCCESS";
  }
}
$$;