Recuperar estatísticas de confirmação para uma transação

Para ajudar você a entender melhor, otimizar e diagnosticar problemas de transações, o Spanner dá acesso às estatísticas de confirmação de transação. Atualmente, é possível recuperar o número total de mutações de uma transação.

Quando usar estatísticas de confirmação

Conhecer a contagem de mutações de uma transação pode ser útil nos cenários a seguir.

Otimizar para viagens de ida e volta

Para melhorar o desempenho do aplicativo, é possível reduzir o número de viagens de ida e volta ao banco de dados fazendo o máximo de trabalho possível em cada transação. Neste cenário, você quer maximizar o número de mutações por transação, mantendo os limites do sistema ao mesmo tempo.

Para determinar quantas linhas você pode confirmar por transação, permanecendo abaixo do limite, primeiro confirme uma linha em uma transação. Com isso, você tem um valor de referência para a contagem de mutações por linha. Em seguida, divida o limite do sistema pelo valor de referência para receber um número de linhas por transação. Para mais informações sobre como as mutações são contadas, consulte esta observação.

Ao usar DML, o limite de 80.000 (incluindo índices) é aplicado por instrução, não por transação. É possível executar várias instruções DML em uma única transação para confirmar mais de 80.000 mutações, sujeito ao limite de tamanho de transação de 100 MiB. Nesse caso, o mutation_count retornado nas estatísticas de confirmação reflete o total de mutações cumulativas (incluindo índices) em todas as instruções e pode exceder 80.000.

Otimizar para viagens de ida e volta nem sempre é benéfico, especialmente se isso resultar em mais contenções de bloqueio. É possível solucionar conflitos de bloqueio em seu banco de dados usando estatísticas de bloqueio.

Como monitorar suas transações para não atingir os limites do sistema

O uso do aplicativo aumenta, é possível que o número de mutações na transação também aumente. Para evitar que o limite do sistema seja atingido e a transação acabe falhando, é possível monitorar proativamente a estatística de confirmação da contagem de mutações ao longo do tempo. Se você observar esse valor aumentando para a mesma transação, talvez seja o momento de reotimizar a transação, conforme descrito na seção anterior.

Como acessar estatísticas de confirmação

Por padrão, as estatísticas de confirmação não são retornadas. Em vez disso, é necessário definir a return_commit_stats sinalização como verdadeira em cada CommitRequest. Se você usar a API Mutation e a tentativa de confirmação exceder o número máximo permitido de mutações (incluindo índices), a confirmação falhará e um erro INVALID_ARGUMENT será retornado. Para DML, exceder o limite de mutação (incluindo índices) faz com que a instrução DML individual falhe durante a execução com um erro BadUsage, em vez de falhar no momento da confirmação.

Confira um exemplo de como retornar estatísticas de confirmação usando as bibliotecas de cliente do Spanner.

Recuperar estatísticas de confirmação

O exemplo a seguir mostra como receber estatísticas de confirmação usando as bibliotecas de cliente do Spanner.

C++

O código a seguir chama set_return_stats() em CommitOptions e retorna uma contagem de mutação de 6, porque estamos inserindo ou atualizando duas linhas e três colunas em cada linha.

void GetCommitStatistics(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  auto commit = client.Commit(
      spanner::Mutations{
          spanner::UpdateMutationBuilder(
              "Albums", {"SingerId", "AlbumId", "MarketingBudget"})
              .EmplaceRow(1, 1, 200000)
              .EmplaceRow(2, 2, 400000)
              .Build()},
      google::cloud::Options{}.set<spanner::CommitReturnStatsOption>(true));

  if (!commit) throw std::move(commit).status();
  if (commit->commit_stats) {
    std::cout << "Updated data with " << commit->commit_stats->mutation_count
              << " mutations.\n";
  }
  std::cout << "Update was successful [spanner_get_commit_stats]\n";
}

C#

Em C#, as estatísticas de confirmação não são retornadas diretamente pela API. Em vez disso, eles são registrados no nível de registro Information pelo logger padrão.

O código a seguir ativa a geração de registros de estatísticas de confirmação para todas as transações definindo a propriedade LogCommitStats em SpannerConnectionStringBuilder como true. O código também implementa um agente de registro de amostra que mantém uma referência à resposta de confirmação vista pela última vez. O MutationCount é recuperado dessa resposta e exibido.

using Google.Cloud.Spanner.Data;
using Google.Cloud.Spanner.V1;
using Google.Cloud.Spanner.V1.Internal.Logging;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Threading.Tasks;

public class LogCommitStatsAsyncSample
{
    public async Task<long> LogCommitStatsAsync(string projectId, string instanceId, string databaseId)
    {
        // Commit statistics are logged at level Info by the default logger.
        // This sample uses a custom logger to access the commit statistics.
        // See https://googleapis.github.io/google-cloud-dotnet/docs/Google.Cloud.Spanner.Data/logging.html
        // for more information on how to use loggers.
        var logger = new CommitStatsSampleLogger();
        var options = new SessionPoolOptions();
        var poolManager = SessionPoolManager.Create(options, logger);
        var connectionStringBuilder = new SpannerConnectionStringBuilder
        {
            ConnectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}",
            // Set LogCommitStats to true to enable logging commit statistics for all transactions on the connection.
            // LogCommitStats can also be enabled/disabled for individual Spanner transactions.
            LogCommitStats = true,
            SessionPoolManager = poolManager,
        };

        using var connection = new SpannerConnection(connectionStringBuilder);
        await connection.OpenAsync();

        using var cmd = connection.CreateDmlCommand("INSERT Singers (SingerId, FirstName, LastName) VALUES (110, 'Virginia', 'Watson')");
        var rowCount = await cmd.ExecuteNonQueryAsync();
        var mutationCount = logger._lastCommitResponse.CommitStats.MutationCount;

        Console.WriteLine($"{rowCount} row(s) inserted...");
        Console.WriteLine($"{mutationCount} mutation(s) in transaction...");

        return mutationCount;
    }

    /// <summary>
    /// Sample logger that keeps a reference to the last seen commit response.
    /// Use the default logger if you only want to log the commit stats.
    /// </summary>
    public class CommitStatsSampleLogger : Logger
    {
        internal CommitResponse _lastCommitResponse;

        /// <summary>
        /// This method is called when a transaction that requested commit stats is committed.
        /// </summary>
        public override void LogCommitStats(CommitRequest request, CommitResponse response)
        {
            _lastCommitResponse = response;
            base.LogCommitStats(request, response);
        }

        protected override void LogImpl(LogLevel level, string message, Exception exception) =>
            WriteLine(exception == null ? $"{level}: {message}" : $"{level}: {message}, Exception: {exception}");

        protected override void LogPerformanceEntries(IEnumerable<string> entries)
        {
            string separator = Environment.NewLine + "  ";
            WriteLine($"Performance:{separator}{string.Join(separator, entries)}");
        }

        private void WriteLine(string line) => Trace.TraceInformation(line);
    }
}

Go

O código a seguir define a sinalização ReturnCommitStats e imprime a contagem de mutações quando a transação é confirmada com êxito.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
)

func commitStats(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return fmt.Errorf("commitStats.NewClient: %w", err)
	}
	defer client.Close()

	resp, err := client.ReadWriteTransactionWithOptions(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
		stmt := spanner.Statement{
			SQL: `INSERT Singers (SingerId, FirstName, LastName)
					VALUES (110, 'Virginia', 'Watson')`,
		}
		rowCount, err := txn.Update(ctx, stmt)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%d record(s) inserted.\n", rowCount)
		return nil
	}, spanner.TransactionOptions{CommitOptions: spanner.CommitOptions{ReturnCommitStats: true}})
	if err != nil {
		return fmt.Errorf("commitStats.ReadWriteTransactionWithOptions: %w", err)
	}
	fmt.Fprintf(w, "%d mutations in transaction\n", resp.CommitStats.MutationCount)
	return nil
}

Java

import com.google.cloud.spanner.CommitResponse;
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Mutation;
import com.google.cloud.spanner.Options;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import java.util.Arrays;

public class GetCommitStatsSample {

  static void getCommitStats() {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "my-project";
    final String instanceId = "my-instance";
    final String databaseId = "my-database";

    try (Spanner spanner =
        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
      final DatabaseClient databaseClient = spanner
          .getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
      getCommitStats(databaseClient);
    }
  }

  static void getCommitStats(DatabaseClient databaseClient) {
    final CommitResponse commitResponse = databaseClient.writeWithOptions(Arrays.asList(
        Mutation.newInsertOrUpdateBuilder("Albums")
            .set("SingerId")
            .to("1")
            .set("AlbumId")
            .to("1")
            .set("MarketingBudget")
            .to("200000")
            .build(),
        Mutation.newInsertOrUpdateBuilder("Albums")
            .set("SingerId")
            .to("2")
            .set("AlbumId")
            .to("2")
            .set("MarketingBudget")
            .to("400000")
            .build()
    ), Options.commitStats());

    System.out.println(
        "Updated data with " + commitResponse.getCommitStats().getMutationCount() + " mutations.");
  }
}

Node.js

O código a seguir define a sinalização returnCommitStats e retorna uma contagem de mutação de 6, porque estamos inserindo ou atualizando duas linhas e três colunas em cada linha.

// Imports the Google Cloud client library.
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client.
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database.
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

// Instantiate Spanner table objects.
const albumsTable = database.table('Albums');

// Updates rows in the Venues table.
try {
  const [response] = await albumsTable.upsert(
    [
      {SingerId: '1', AlbumId: '1', MarketingBudget: '200000'},
      {SingerId: '2', AlbumId: '2', MarketingBudget: '400000'},
    ],
    {returnCommitStats: true},
  );
  console.log(
    `Updated data with ${response.commitStats.mutationCount} mutations.`,
  );
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

PHP

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Transaction;

/**
 * Creates a database and tables for sample data.
 * Example:
 * ```
 * create_database($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function get_commit_stats(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $commitStats = $database->runTransaction(function (Transaction $t) {
        $t->updateBatch('Albums', [
            [
                'SingerId' => 1,
                'AlbumId' => 1,
                'MarketingBudget' => 200000,
            ],
            [
                'SingerId' => 2,
                'AlbumId' => 2,
                'MarketingBudget' => 400000,
            ]
        ]);
        $t->commit(['returnCommitStats' => true]);
        return $t->getCommitStats();
    });

    print('Updated data with ' . $commitStats['mutationCount'] . ' mutations.' . PHP_EOL);
}

Python

Em vez de retornar estatísticas de confirmação diretamente pela API, a biblioteca de cliente Python as registra usando stdout no nível Info.

O código a seguir ativa a geração de registros de estatísticas de confirmação para todas as transações com a configuração de database.log_commit_stats = True. O código também implementa um logger de amostra que mantém uma referência à última resposta de confirmação vista. O mutation_count é recuperado a partir dessa resposta e exibido.

def log_commit_stats(instance_id, database_id):
    """Inserts sample data using DML and displays the commit statistics."""

    # By default, commit statistics are logged via stdout at level Info.
    # This sample uses a custom logger to access the commit statistics.
    class CommitStatsSampleLogger(logging.Logger):
        def __init__(self):
            self.last_commit_stats = None
            super().__init__("commit_stats_sample")

        def info(self, msg, *args, **kwargs):
            if (
                "extra" in kwargs
                and kwargs["extra"]
                and "commit_stats" in kwargs["extra"]
            ):
                self.last_commit_stats = kwargs["extra"]["commit_stats"]
            super().info(msg, *args, **kwargs)

    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id, logger=CommitStatsSampleLogger())
    database.log_commit_stats = True

    def insert_singers(transaction):
        row_ct = transaction.execute_update(
            "INSERT Singers (SingerId, FirstName, LastName) "
            " VALUES (110, 'Virginia', 'Watson')"
        )

        print("{} record(s) inserted.".format(row_ct))

    database.run_in_transaction(insert_singers)
    commit_stats = database.logger.last_commit_stats
    print("{} mutation(s) in transaction.".format(commit_stats.mutation_count))

Ruby

O código a seguir define a sinalização return_commit_stats e retorna uma contagem de mutação de 6, porque estamos inserindo ou atualizando duas linhas e três colunas em cada linha.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

records = [
  { SingerId: 1, AlbumId: 1, MarketingBudget: 200_000 },
  { SingerId: 2, AlbumId: 2, MarketingBudget: 400_000 }
]
commit_options = { return_commit_stats: true }
resp = client.upsert "Albums", records, commit_options: commit_options
puts "Updated data with #{resp.stats.mutation_count} mutations."

A seguir

• Referência da confirmação REST CommitStats.
• Referência do commit do gRPC