Saltar al contenido principal

Registro

El ejemplo de registro demuestra cómo registrar con el propósito de depuración.

Abrir en Gitpod

Los registros en los contratos solo son visibles en las pruebas, o al ejecutar contratos utilizando stellar-cli. Los registros solo se compilan en el contrato si la opción del compilador Rust debug-assertions está habilitada.

consejo

Los registros no son un sustituto para la depuración paso a paso. Las pruebas de Rust para Soroban se pueden depurar paso a paso en tu IDE habilitado para Rust. Consulta pruebas para más detalles.

advertencia

Los registros no son accesibles por dapps y otras aplicaciones. Consulta el ejemplo de eventos para saber cómo producir eventos estructurados.

Ejecutar el ejemplo​

Primero, pasa por el proceso de Configuración para configurar tu entorno de desarrollo, luego clona la etiqueta v21.6.0 del repositorio soroban-examples:

git clone -b v21.6.0 https://github.com/stellar/soroban-examples

O, salta la configuración del entorno de desarrollo y abre este ejemplo en Gitpod.

Para ejecutar las pruebas del ejemplo, navega al directorio logging, y utiliza cargo test.

cd logging
cargo test -- --nocapture

Deberías ver la salida:

running 1 test
Hello Symbol(Dev)
test test::test ... ok

Código​

Cargo.toml
[profile.release-with-logs]
inherits = "release"
debug-assertions = true
logging/src/lib.rs
#![no_std]
use soroban_sdk::{contractimpl, log, Env, Symbol};

#[contract]
pub struct Contract;

#[contractimpl]
impl Contract {
    pub fn hello(env: Env, value: Symbol) {
        log!(&env, "Hello {}", value);
    }
}

Ref: https://github.com/stellar/soroban-examples/tree/v21.6.0/logging

Cómo funciona​

El macro log! registra una cadena. Todos los registros que ocurren durante la ejecución se envían a stdout en stellar-cli y están disponibles para que las pruebas validen o impriman.

Los registros solo se envían si el contrato se construye con la opción del compilador debug-assertions habilitada. Esto hace que sea eficiente dejarlos en el código de forma permanente, ya que una construcción release regular los omitirá.

Los registros solo se almacenan en los entornos de Soroban que tienen el registro habilitado. Los únicos entornos de Soroban donde el registro está habilitado son en las pruebas de Rust, y en el stellar-cli.

Abre los archivos anteriores para seguirlo.

Cargo.toml Perfil​

Los registros solo se envían si el contrato se construye con la opción del compilador debug-assertions habilitada.

El perfil test que se activa al ejecutar cargo test tiene habilitadas las debug-assertions, así que al ejecutar pruebas, los registros están habilitados por defecto.

Se añade un nuevo perfil release-with-logs a Cargo.toml que hereda del perfil release, y habilita debug-assertions. Se puede utilizar para construir un archivo .wasm que tiene los registros habilitados.

[profile.release-with-logs]
inherits = "release"
debug-assertions = true

Para construir sin registros utiliza la opción --release o --profile release.

Para construir con registros utiliza la opción --profile release-with-logs.

Usando el macro log!​

El macro log! construye una cadena a partir de la cadena de formato y una lista de argumentos. Los argumentos se sustituyen dondequiera que aparezca el valor {} en la cadena de formato.

log!(&env, "Hello {}", value);

El registro anterior se representará como sigue si value es un Symbol que contiene "Dev".

Hello Symbol(Dev)
advertencia

Los valores enviados actualmente son relativamente limitados. Mientras que valores primitivos como u32, u64, bool, y Symbols se representarán claramente en la salida del registro, Bytes, Vec, Map, y tipos personalizados solo representarán su número de identificador. Las capacidades de registro están en desarrollo inicial.

Pruebas​

Abre el archivo logging/src/test.rs para seguirlo.

logging/src/test.rs
extern crate std;

#[test]
fn test() {
    let env = Env::default();
    let contract_id = env.register_contract(None, Contract);
    let client = ContractClient::new(&env, &contract_id);

    client.hello(&symbol_short!("Dev"));

    let logs = env.logs().all();
    assert_eq!(logs, std::vec!["Hello Symbol(Dev)"]);
    std::println!("{}", logs.join("\n"));
}

El crate std, que contiene la biblioteca estándar de Rust, se importa para que la prueba pueda usar los macros std::vec! y std::println!. Dado que los contratos deben usar #![no_std], las pruebas en contratos deben importar manualmente std para usar la funcionalidad estándar como imprimir en stdout.

extern crate std;

En cualquier prueba, lo primero que siempre se requiere es un Env, que es el entorno de Soroban en el que se ejecutará el contrato.

let env = Env::default();

El contrato se registra con el entorno utilizando el tipo de contrato.

let contract_id = env.register_contract(None, HelloContract);

Todas las funciones públicas dentro de un bloque impl que está anotado con el atributo #[contractimpl] tienen una función correspondiente generada en un tipo de cliente generado. El tipo de cliente se nombrará igual que el tipo de contrato con Client añadido. Por ejemplo, en nuestro contrato, el tipo de contrato es HelloContract, y el cliente se llama HelloContractClient.

let client = HelloContractClient::new(&env, &contract_id);
let words = client.hello(&symbol_short!("Dev"));

Los registros están disponibles en las pruebas a través del entorno.

let logs = env.logs().all();

Se pueden validar como cualquier otro valor.

assert_eq!(logs, std::vec!["Hello Symbol(Dev)"]);

Se pueden imprimir en stdout.

std::println!("{}", logs.join("\n"));

Construir el contrato​

Para construir el contrato, utiliza el comando stellar contract build.

Sin registros​

Para construir el contrato sin registros, utiliza la opción --release.

stellar contract build

Un archivo .wasm debería ser enviado al directorio target, en el subdirectorio release:

target/wasm32-unknown-unknown/release/soroban_logging_contract.wasm

Con registros​

Para construir el contrato con registros, utiliza la opción --profile release-with-logs.

stellar contract build --profile release-with-logs

Un archivo .wasm debería ser enviado al directorio target, en el subdirectorio release-with-logs:

target/wasm32-unknown-unknown/release-with-logs/soroban_logging_contract.wasm

Ejecutar el contrato​

Si tienes stellar-cli instalado, puedes invocar funciones del contrato usándolo. Especifica la opción -v para habilitar registros detallados.

stellar -v contract invoke \
    --wasm target/wasm32-unknown-unknown/release-with-logs/soroban_logging_contract.wasm \
    --id 1 \
    -- \
    hello \
    --value friend

La salida debe incluir la siguiente línea.

stellar_cli::log::event::contract_log: log="Hello Symbol(me)"