Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Risolvere i problemi relativi ai tag di richiesta e di transazione

Spanner fornisce un insieme di tabelle delle statistiche integrate per aiutarti a ottenere informazioni dettagliate su query, letture e transazioni. Per correlare le statistiche al codice dell'applicazione e migliorare la risoluzione dei problemi, puoi aggiungere un tag (una stringa in formato libero) alle operazioni di lettura, query e transazione di Spanner nel codice dell'applicazione. Questi tag vengono inseriti nelle tabelle delle statistiche per aiutarti a correlare e cercare in base ai tag.

Spanner supporta due tipi di tag: tag richiesta e tag transazione. Come suggeriscono i nomi, puoi aggiungere tag di transazione alle transazioni e tag di richiesta alle singole query e alle API di lettura. Puoi impostare un tag di transazione nell'ambito della transazione e impostare singoli tag di richiesta per ogni richiesta API applicabile all'interno della transazione. I tag di richiesta e di transazione impostati nel codice dell'applicazione vengono inseriti nelle colonne delle seguenti tabelle delle statistiche.

Tabella delle statistiche	Tipo di tag compilati nella tabella delle statistiche
Statistiche sulle query TopN	Tag di richiesta
Statistiche sulle letture TopN	Tag di richiesta
Statistiche sulle transazioni TopN	Tag transazione
Statistiche sui blocchi TopN	Tag transazione

Tag di richiesta

Puoi aggiungere un tag di richiesta facoltativo a una query o a una richiesta di lettura. Spanner raggruppa le statistiche per tag di richiesta, visibile nel campo REQUEST_TAG delle tabelle statistiche query e statistiche di lettura.

Quando utilizzare i tag di richiesta

Di seguito sono riportati alcuni scenari che traggono vantaggio dall'utilizzo dei tag di richiesta.

Trovare l'origine di una query o di una lettura problematica:Spanner raccoglie statistiche per letture e query in tabelle delle statistiche integrate. Quando trovi le query lente o le letture che consumano molta CPU nella tabella delle statistiche, se hai già assegnato tag, puoi identificare l'origine (applicazione/microservizio) che chiama queste operazioni in base alle informazioni nel tag.
Identificazione di letture o query nelle tabelle delle statistiche:l'assegnazione di tag alle richieste consente di filtrare le righe nella tabella delle statistiche in base ai tag di tuo interesse.
Verificare se le query di una particolare applicazione o microservizio sono lente: i tag delle richieste possono aiutarti a identificare se le query di una particolare applicazione o microservizio hanno latenze più elevate.
Raggruppamento delle statistiche per un insieme di letture o query:puoi utilizzare i tag di richiesta per monitorare, confrontare e generare report sul rendimento di un insieme di letture o query simili. Ad esempio, se più query accedono a una tabella o a un insieme di tabelle con lo stesso pattern di accesso, puoi valutare la possibilità di aggiungere lo stesso tag a tutte queste query per monitorarle insieme.

Come assegnare i tag alle richieste

Il seguente esempio mostra come impostare i tag di richiesta utilizzando le librerie client di Spanner.

C++

void SetRequestTag(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;

  auto opts = google::cloud::Options{}.set<spanner::RequestTagOption>(
      "app=concert,env=dev,action=select");
  auto rows = client.ExecuteQuery(std::move(select), std::move(opts));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
}

C#


using Google.Cloud.Spanner.Data;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class RequestTagAsyncSample
{
    public class Album
    {
        public int SingerId { get; set; }
        public int AlbumId { get; set; }
        public string AlbumTitle { get; set; }
    }

    public async Task<List<Album>> RequestTagAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        using var cmd = connection.CreateSelectCommand(
            $"SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        // Sets the request tag to "app=concert,env=dev,action=select".
        // This request tag will only be set on this request.
        cmd.Tag = "app=concert,env=dev,action=select";

        var albums = new List<Album>();
        using var reader = await cmd.ExecuteReaderAsync();
        while (await reader.ReadAsync())
        {
            var album = new Album
            {
                SingerId = reader.GetFieldValue<int>("SingerId"),
                AlbumId = reader.GetFieldValue<int>("AlbumId"),
                AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
            };
            albums.Add(album);
            Console.WriteLine($"SingerId: {album.SingerId}, AlbumId: {album.AlbumId}, AlbumTitle: {album.AlbumTitle}");
        }
        return albums;
    }
}

Go


import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	"google.golang.org/api/iterator"
)

// queryWithTag reads from a database with request tag set
func queryWithTag(w io.Writer, db string) error {
	// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
	iter := client.Single().QueryWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=select"})
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var singerID, albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
	}
}

Java

static void setRequestTag(DatabaseClient databaseClient) {
  // Sets the request tag to "app=concert,env=dev,action=select".
  // This request tag will only be set on this request.
  try (ResultSet resultSet = databaseClient
      .singleUse()
      .executeQuery(
          Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"),
          Options.tag("app=concert,env=dev,action=select"))) {
    while (resultSet.next()) {
      System.out.printf(
          "SingerId: %d, AlbumId: %d, AlbumTitle: %s\n",
          resultSet.getLong(0),
          resultSet.getLong(1),
          resultSet.getString(2));
    }
  }
}

Node.js

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

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

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

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

  // Execute a query with a request tag.
  const [albums] = await database.run({
    sql: 'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
    requestOptions: {requestTag: 'app=concert,env=dev,action=select'},
    json: true,
  });
  albums.forEach(album => {
    console.log(
      `SingerId: ${album.SingerId}, AlbumId: ${album.AlbumId}, AlbumTitle: ${album.AlbumTitle}`,
    );
  });
  await database.close();
}
queryTags();

PHP

use Google\Cloud\Spanner\SpannerClient;

/**
 * Executes a read with a request tag.
 * Example:
 * ```
 * spanner_set_request_tag($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function set_request_tag(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $snapshot = $database->snapshot();
    $results = $snapshot->execute(
        'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
        [
            'requestOptions' => [
                'requestTag' => 'app=concert,env=dev,action=select'
            ]
        ]
    );
    foreach ($results as $row) {
        printf('SingerId: %s, AlbumId: %s, AlbumTitle: %s' . PHP_EOL,
            $row['SingerId'], $row['AlbumId'], $row['AlbumTitle']);
    }
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

with database.snapshot() as snapshot:
    results = snapshot.execute_sql(
        "SELECT SingerId, AlbumId, AlbumTitle FROM Albums",
        request_options={"request_tag": "app=concert,env=dev,action=select"},
    )

    for row in results:
        print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

Ruby

# 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

client.execute(
  "SELECT SingerId, AlbumId, MarketingBudget FROM Albums",
  request_options: { tag: "app=concert,env=dev,action=select" }
).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:MarketingBudget]}"
end

Come visualizzare i tag delle richieste nella tabella delle statistiche

La seguente query restituisce le statistiche delle query a intervalli di 10 minuti.

SELECT t.text,
       t.request_tag,
       t.execution_count,
       t.avg_latency_seconds,
       t.avg_rows,
       t.avg_bytes
FROM SPANNER_SYS.QUERY_STATS_TOP_10MINUTE AS t
LIMIT 3;

I seguenti dati sono un esempio dei risultati restituiti dalla query.

sms	request_tag	execution_count	avg_latency_seconds	avg_rows	avg_bytes
SELECT SingerId, AlbumId, AlbumTitle FROM Albums	app=concerto,env=dev,action=select	212	0,025	21	2365
select * from orders;	app=catalogsearch,env=dev,action=list	55	0,02	16	33,35
SELECT SingerId, FirstName, LastName FROM Singers;	[stringa vuota]	154	0,048	42	486,33

Da questa tabella dei risultati, possiamo vedere che se hai assegnato un REQUEST_TAG a una query, questo viene inserito nella tabella delle statistiche. Se non è assegnato alcun tag di richiesta, viene visualizzato come stringa vuota.

Per le query taggate, le statistiche vengono aggregate per tag (ad es. il tag della richiesta app=concert,env=dev,action=select ha una latenza media di 0,025 secondi). Se non è assegnato alcun tag, le statistiche vengono aggregate per query (ad es. la query nella terza riga ha una latenza media di 0,048 secondi).

Tag transazione

È possibile aggiungere un tag transazione facoltativo alle singole transazioni. Spanner raggruppa le statistiche in base al tag transazione, visibile nel campo TRANSACTION_TAG delle tabelle delle statistiche delle transazioni.

Quando utilizzare i tag transazione

Di seguito sono riportati alcuni scenari che traggono vantaggio dall'utilizzo dei tag transazione.

Individuare l'origine di una transazione problematica:Spanner raccoglie statistiche per le transazioni di lettura/scrittura nella tabella delle statistiche delle transazioni. Quando trovi transazioni lente nella tabella delle statistiche delle transazioni, se hai già assegnato tag, puoi identificare l'origine (applicazione/microservizio) che chiama queste transazioni in base alle informazioni nel tag.
Identificazione delle transazioni nelle tabelle delle statistiche: l'assegnazione di tag alle transazioni consente di filtrare le righe nella tabella delle statistiche delle transazioni in base ai tag che ti interessano. Senza i tag transazione, scoprire quali operazioni sono rappresentate da una statistica può essere un processo macchinoso. Ad esempio, per le statistiche sulle transazioni, devi esaminare le tabelle e le colonne coinvolte per identificare la transazione senza tag.
Verificare se le transazioni di una determinata applicazione o microservizio sono lente: i tag delle transazioni possono aiutare a identificare se le transazioni di una determinata applicazione o microservizio hanno latenze più elevate.
Statistiche di raggruppamento per un insieme di transazioni:puoi utilizzare i tag transazione per monitorare, confrontare e generare report sul rendimento di un insieme di transazioni simili.
Individuare le transazioni che accedono alle colonne coinvolte nel conflitto di blocco: i tag transazione possono aiutarti a individuare le singole transazioni che causano conflitti di blocco nelle tabelle Statistiche di blocco.
Streaming dei dati delle modifiche degli utenti da Spanner utilizzando le modifiche in tempo reale: i record di dati delle modifiche in tempo reale contengono tag di transazione per le transazioni che hanno modificato i dati utente. Ciò consente al lettore di un flusso di modifiche di associare le modifiche al tipo di transazione in base ai tag.

Come assegnare tag alle transazioni

Il seguente esempio mostra come impostare i tag di transazione utilizzando le librerie client Spanner. Quando utilizzi una libreria client, puoi impostare un tag di transazione all'inizio della chiamata di transazione, che viene applicato a tutte le singole operazioni all'interno della transazione.

C++

void SetTransactionTag(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  using ::google::cloud::StatusOr;

  // Sets the transaction tag to "app=concert,env=dev". This will be
  // applied to all the individual operations inside this transaction.
  auto commit_options =
      google::cloud::Options{}.set<spanner::TransactionTagOption>(
          "app=concert,env=dev");
  auto commit = client.Commit(
      [&client](
          spanner::Transaction const& txn) -> StatusOr<spanner::Mutations> {
        spanner::SqlStatement update_statement(
            "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64)"
            "  WHERE OutdoorVenue = false");
        // Sets the request tag to "app=concert,env=dev,action=update".
        // This will only be set on this request.
        auto update = client.ExecuteDml(
            txn, std::move(update_statement),
            google::cloud::Options{}.set<spanner::RequestTagOption>(
                "app=concert,env=dev,action=update"));
        if (!update) return std::move(update).status();

        spanner::SqlStatement insert_statement(
            "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, "
            "                    LastUpdateTime)"
            " VALUES (@venueId, @venueName, @capacity, @outdoorVenue, "
            "         PENDING_COMMIT_TIMESTAMP())",
            {
                {"venueId", spanner::Value(81)},
                {"venueName", spanner::Value("Venue 81")},
                {"capacity", spanner::Value(1440)},
                {"outdoorVenue", spanner::Value(true)},
            });
        // Sets the request tag to "app=concert,env=dev,action=insert".
        // This will only be set on this request.
        auto insert = client.ExecuteDml(
            txn, std::move(insert_statement),
            google::cloud::Options{}.set<spanner::RequestTagOption>(
                "app=concert,env=dev,action=select"));
        if (!insert) return std::move(insert).status();
        return spanner::Mutations{};
      },
      commit_options);
  if (!commit) throw std::move(commit).status();
}

C#


using Google.Cloud.Spanner.Data;
using System.Threading.Tasks;

public class TransactionTagAsyncSample
{
    public async Task<int> TransactionTagAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        return await connection.RunWithRetriableTransactionAsync(async transaction =>
        {
            // Sets the transaction tag to "app=concert,env=dev".
            // This transaction tag will be applied to all the individual operations inside
            // the transaction.
            transaction.TransactionOptions.Tag = "app=concert,env=dev";

            // Sets the request tag to "app=concert,env=dev,action=update".
            // This request tag will only be set on this request.
            var updateCommand =
                connection.CreateDmlCommand("UPDATE Venues SET Capacity = DIV(Capacity, 4) WHERE OutdoorVenue = false");
            updateCommand.Tag = "app=concert,env=dev,action=update";
            updateCommand.Transaction = transaction;
            int rowsModified = await updateCommand.ExecuteNonQueryAsync();

            var insertCommand = connection.CreateDmlCommand(
                @"INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)
                    VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())",
                new SpannerParameterCollection
                {
                    {"venueId", SpannerDbType.Int64, 81},
                    {"venueName", SpannerDbType.String, "Venue 81"},
                    {"capacity", SpannerDbType.Int64, 1440},
                    {"outdoorVenue", SpannerDbType.Bool, true}
                }
            );
            // Sets the request tag to "app=concert,env=dev,action=insert".
            // This request tag will only be set on this request.
            insertCommand.Tag = "app=concert,env=dev,action=insert";
            insertCommand.Transaction = transaction;
            rowsModified += await insertCommand.ExecuteNonQueryAsync();
            return rowsModified;
        });
    }
}

Go


import (
	"context"
	"fmt"
	"io"

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

// readWriteTransactionWithTag executes the update and insert queries on venues table with appropriate transaction and requests tag
func readWriteTransactionWithTag(w io.Writer, db string) error {
	// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	_, err = client.ReadWriteTransactionWithOptions(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
		stmt := spanner.Statement{
			SQL: `UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false`,
		}
		_, err := txn.UpdateWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=update"})
		if err != nil {
			return err
		}
		fmt.Fprint(w, "Venue capacities updated.")
		stmt = spanner.Statement{
			SQL: `INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime) 
                   VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())`,
			Params: map[string]interface{}{
				"venueId":      81,
				"venueName":    "Venue 81",
				"capacity":     1440,
				"outdoorVenue": true,
			},
		}
		_, err = txn.UpdateWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=insert"})
		if err != nil {
			return err
		}
		fmt.Fprint(w, "New venue inserted.")
		return nil
	}, spanner.TransactionOptions{TransactionTag: "app=concert,env=dev"})
	return err
}

Java

static void setTransactionTag(DatabaseClient databaseClient) {
  // Sets the transaction tag to "app=concert,env=dev".
  // This transaction tag will be applied to all the individual operations inside this
  // transaction.
  databaseClient
      .readWriteTransaction(Options.tag("app=concert,env=dev"))
      .run(transaction -> {
        // Sets the request tag to "app=concert,env=dev,action=update".
        // This request tag will only be set on this request.
        transaction.executeUpdate(
            Statement.of("UPDATE Venues"
                + " SET Capacity = CAST(Capacity/4 AS INT64)"
                + " WHERE OutdoorVenue = false"),
            Options.tag("app=concert,env=dev,action=update"));
        System.out.println("Venue capacities updated.");

        Statement insertStatement = Statement.newBuilder(
            "INSERT INTO Venues"
                + " (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)"
                + " VALUES ("
                + " @venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP()"
                + " )")
            .bind("venueId")
            .to(81)
            .bind("venueName")
            .to("Venue 81")
            .bind("capacity")
            .to(1440)
            .bind("outdoorVenue")
            .to(true)
            .build();

        // Sets the request tag to "app=concert,env=dev,action=insert".
        // This request tag will only be set on this request.
        transaction.executeUpdate(
            insertStatement,
            Options.tag("app=concert,env=dev,action=insert"));
        System.out.println("New venue inserted.");

        return null;
      });
}

Node.js

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

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

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

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

  // Run a transaction with a transaction tag that will automatically be
  // included with each request in the transaction.
  try {
    await database.runTransactionAsync(
      {requestOptions: {transactionTag: 'app=cart,env=dev'}},
      async tx => {
        // Set the request tag to "app=concert,env=dev,action=update".
        // This request tag will only be set on this request.
        await tx.runUpdate({
          sql: 'UPDATE Venues SET Capacity = DIV(Capacity, 4) WHERE OutdoorVenue = false',
          requestOptions: {requestTag: 'app=concert,env=dev,action=update'},
        });
        console.log('Updated capacity of all indoor venues to 1/4.');

        await tx.runUpdate({
          sql: `INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)
                VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())`,
          params: {
            venueId: 81,
            venueName: 'Venue 81',
            capacity: 1440,
            outdoorVenue: true,
          },
          types: {
            venueId: {type: 'int64'},
            venueName: {type: 'string'},
            capacity: {type: 'int64'},
            outdoorVenue: {type: 'bool'},
          },
          requestOptions: {requestTag: 'app=concert,env=dev,action=update'},
        });
        console.log('Inserted new outdoor venue');

        await tx.commit();
      },
    );
  } catch (err) {
    console.error('ERROR:', err);
  } finally {
    await database.close();
  }
}
transactionTag();

PHP

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

/**
 * Executes a transaction with a transaction tag.
 * Example:
 * ```
 * spanner_set_transaction_tag($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function set_transaction_tag(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $database->runTransaction(function (Transaction $t) {
        $t->executeUpdate(
            'UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false',
            [
                'requestOptions' => ['requestTag' => 'app=concert,env=dev,action=update']
            ]
        );
        print('Venue capacities updated.' . PHP_EOL);
        $t->executeUpdate(
            'INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime) '
            . 'VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())',
            [
                'parameters' => [
                    'venueId' => 81,
                    'venueName' => 'Venue 81',
                    'capacity' => 1440,
                    'outdoorVenue' => true,
                ],
                'requestOptions' => ['requestTag' => 'app=concert,env=dev,action=insert']
            ]
        );
        print('New venue inserted.' . PHP_EOL);
        $t->commit();
    }, [
        'requestOptions' => ['transactionTag' => 'app=concert,env=dev']
    ]);
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

def update_venues(transaction):
    # Sets the request tag to "app=concert,env=dev,action=update".
    #  This request tag will only be set on this request.
    transaction.execute_update(
        "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false",
        request_options={"request_tag": "app=concert,env=dev,action=update"},
    )
    print("Venue capacities updated.")

    # Sets the request tag to "app=concert,env=dev,action=insert".
    # This request tag will only be set on this request.
    transaction.execute_update(
        "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime) "
        "VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())",
        params={
            "venueId": 81,
            "venueName": "Venue 81",
            "capacity": 1440,
            "outdoorVenue": True,
        },
        param_types={
            "venueId": param_types.INT64,
            "venueName": param_types.STRING,
            "capacity": param_types.INT64,
            "outdoorVenue": param_types.BOOL,
        },
        request_options={"request_tag": "app=concert,env=dev,action=insert"},
    )
    print("New venue inserted.")

database.run_in_transaction(update_venues, transaction_tag="app=concert,env=dev")

Ruby

# 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

client.transaction request_options: { tag: "app=cart,env=dev" } do |tx|
  tx.execute_update \
    "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false",
    request_options: { tag: "app=concert,env=dev,action=update" }

  puts "Venue capacities updated."

  tx.execute_update \
    "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue) " \
    "VALUES (@venue_id, @venue_name, @capacity, @outdoor_venue)",
    params: {
      venue_id: 81,
      venue_name: "Venue 81",
      capacity: 1440,
      outdoor_venue: true
    },
    request_options: { tag: "app=concert,env=dev,action=insert" }

  puts "New venue inserted."
end

Come visualizzare i tag delle transazioni nella tabella delle statistiche delle transazioni

La seguente query restituisce le statistiche sulle transazioni a intervalli di 10 minuti.

SELECT t.fprint,
       t.transaction_tag,
       t.read_columns,
       t.commit_attempt_count,
       t.avg_total_latency_seconds
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE AS t
LIMIT 3;

I seguenti dati sono un esempio dei risultati restituiti dalla query.

fprint	transaction_tag	read_columns	commit_attempt_count	avg_total_latency_seconds
40015598317	app=concert,env=dev	[Venues._exists, Venues.VenueId, Venues.VenueName, Venues.Capacity]	278802	0,3508
20524969030	app=product,service=payment	[Singers.SingerInfo]	129012	0,0142
77848338483	[stringa vuota]	[Singers.FirstName, Singers.LastName, Singers._exists]	5357	0,048

Da questa tabella dei risultati, possiamo vedere che se hai assegnato un TRANSACTION_TAG a una transazione, questo viene inserito nella tabella delle statistiche delle transazioni. Se non è assegnato alcun tag transazione, viene visualizzata una stringa vuota.

Per le transazioni taggate, le statistiche vengono aggregate per tag di transazione (ad es. il tag di transazione app=concert,env=dev a ha una latenza media di 0,3508 secondi). Se non è assegnato alcun tag, le statistiche vengono aggregate per FPRINT (ad es. 77848338483 nella terza riga ha una latenza media di 0,048 secondi).

Come visualizzare i tag delle transazioni nella tabella delle statistiche di chiusura

La seguente query restituisce le statistiche di blocco a intervalli di 10 minuti.

La funzione CAST() converte il campo row_range_start_key BYTES in una STRINGA.

SELECT
   CAST(s.row_range_start_key AS STRING) AS row_range_start_key,
   s.lock_wait_seconds,
   s.sample_lock_requests
FROM SPANNER_SYS.LOCK_STATS_TOP_10MINUTE s
LIMIT 2;

I seguenti dati sono un esempio dei risultati restituiti dalla query.

row_range_start_key	lock_wait_seconds	sample_lock_requests
Brani(2,1,1)	0,61	LOCK_MODE: ReaderShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=product,service=shipping LOCK_MODE: WriterShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=product,service=payment
album(2,1+)	0,48	LOCK_MODE: ReaderShared COLUMN: users._exists1 TRANSACTION_TAG: [empty string] LOCK_MODE: WriterShared COLUMN: users._exists TRANSACTION_TAG: [empty string]

Da questa tabella dei risultati, possiamo vedere che se hai assegnato un TRANSACTION_TAG a una transazione, questo viene inserito nella tabella delle statistiche della serratura. Se non è assegnato alcun tag transazione, viene visualizzata una stringa vuota.

Assegnare automaticamente i tag

Le librerie client di Spanner supportano l'assegnazione automatica di tag allo stack di chiamate. Quando il tagging automatico è attivato, la libreria client esamina lo stack di chiamate di esecuzione dell'applicazione per determinare la classe e il metodo che hanno avviato la richiesta di database. Genera automaticamente un tag in base a questi nomi (ad esempio, OrderDao.placeOrder in Java o db__OrderDao__PlaceOrder in Go) e compila request_tag o transaction_tag.

Il tagging automatico è supportato nelle seguenti librerie client:

Java versione 6.118.0 e successive.
Go versione 1.92.0 e successive.

Considerazioni per il tagging automatico

Prima di utilizzare il tagging automatico, considera questi aspetti:

Overhead di CPU e latenza: l'ispezione degli stack di chiamate di runtime utilizzando la reflection o l'attraversamento dello stack di chiamate di runtime su ogni richiesta e transazione introduce un overhead di CPU e latenza. Prima di forzare l'attivazione del tagging automatico a livello globale negli ambienti di produzione con QPS elevato, valuta l'impatto sul rendimento dei tuoi servizi.
Differenze rispetto al tagging chiave-valore:i tag generati automaticamente (ad esempio OrderDao.placeOrder) identificano i simboli di origine del codice anziché i metadati chiave-valore strutturati (ad esempio app=cart,env=dev). Se le query di monitoraggio filtrano le tabelle delle statistiche utilizzando prefissi di chiave come STARTS_WITH(request_tag, "app="), le operazioni con tag automatici non corrispondono a questi filtri.
Cardinalità dei tag:i nomi dei metodi dinamici o molto sovraccarichi possono aumentare la cardinalità dei tag nelle tabelle delle statistiche. Se il numero di tag unici supera la capacità di monitoraggio di Spanner durante un intervallo, Spanner assegna la priorità alle operazioni di monitoraggio con il consumo di risorse più elevato.
Divulgazione di informazioni:poiché i tag vengono archiviati in testo normale nelle tabelle delle statistiche SPANNER_SYS, i nomi di classi e metodi interni sono visibili a chiunque abbia accesso alle statistiche del database di query. Evita di utilizzare terminologia aziendale sensibile nei nomi di metodi o classi se l'accesso al monitoraggio è condiviso tra più confini.

Attivare e disattivare il tagging automatico

Puoi configurare il tagging automatico nel codice o impostare le impostazioni a livello globale con le variabili di ambiente.

Regole di priorità della configurazione

Se assegni manualmente un request_tag o un transaction_tag a una richiesta o a un generatore di transazioni, questo tag ha sempre la precedenza su qualsiasi tag dello stack di chiamate generato automaticamente. Se non è presente alcun tag manuale, la configurazione del tagging automatico segue queste regole di priorità:

Override di disattivazione forzata:se SPANNER_DISABLE_AUTO_TAGGING=true è impostato, il tagging automatico viene disattivato completamente a livello globale, ignorando le configurazioni programmatiche.
Forza attivazione override:se SPANNER_ENABLE_AUTO_TAGGING=true è impostato, il tagging automatico viene attivato a livello globale, sostituendo le configurazioni programmatiche.
Configurazione programmatica:se non sono impostate variabili di ambiente di override, la libreria utilizza la configurazione programmatica impostata in SpannerOptions (Java) o ClientConfig (Go).
Comportamento predefinito: se non configuri il tagging automatico, questo è disattivato per impostazione predefinita.

Override globali

Per forzare l'attivazione o la disattivazione del tagging automatico a livello globale senza modificare il codice dell'applicazione, imposta le variabili di ambiente nell'ambiente runtime:

# Force-enable globally
export SPANNER_ENABLE_AUTO_TAGGING=true

# Force-disable globally (overrides code configuration)
export SPANNER_DISABLE_AUTO_TAGGING=true

Configurazione programmatica

Gli esempi seguenti mostrano come attivare il tagging automatico dello stack di chiamate utilizzando le librerie client Spanner.

Go

package main

import (
    "context"
    "cloud.google.com/go/spanner"
)

func main() {
    ctx := context.Background()
    config := spanner.ClientConfig{
        // Enable call-stack autotagging
        EnableAutoTagging: true,
        // Optional: Specify target application package prefixes
        AutoTaggingPackages: []string{"github.com/mycompany/orderingservice"},
        // Optional: Set maximum stack depth to inspect (default is 50)
        AutoTaggingTracerLimit: 50,
    }
    client, err := spanner.NewClientWithConfig(ctx, "projects/p/instances/i/databases/d", config)
    if err != nil {
        panic(err)
    }
    defer client.Close()
}

Java

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import java.util.Arrays;

SpannerOptions options = SpannerOptions.newBuilder()
    // Enable call-stack autotagging
    .enableAutoTagging()
    // Optional: Specify target application package prefixes
    .setAutoTaggingPackages(Arrays.asList("com.mycompany.orderingservice."))
    // Optional: Set maximum stack depth to inspect (default is 50)
    .setAutoTaggingTracerLimit(100)
    .build();
Spanner spanner = options.getService();

Mappatura tra i metodi API e i tag di richiesta e di transazione

I tag di richiesta e i tag di transazione sono applicabili a metodi API specifici a seconda che la modalità di transazione sia di sola lettura o di lettura/scrittura. In genere, i tag di transazione sono applicabili alle transazioni di lettura/scrittura, mentre i tag di richiesta sono applicabili alle transazioni di sola lettura. La tabella seguente mostra il mapping dai metodi API ai tipi di tag applicabili.

Metodi API	Modalità di transazione	Tag richiesta	Tag transazione
Read, StreamingRead	Transazione di sola lettura	Sì	No
Read, StreamingRead	Transazione di lettura/scrittura	Sì	Sì
ExecuteSql, ExecuteStreamingSql¹	Transazione di sola lettura¹	Sì¹	No
ExecuteSql, ExecuteStreamingSql¹	Transazione di lettura/scrittura	Sì	Sì
ExecuteBatchDml	Transazione di lettura/scrittura	Sì	Sì
BeginTransaction	Transazione di lettura/scrittura	No	Sì
Esegui il commit	Transazione di lettura/scrittura	No	Sì

¹ Per le query di stream delle modifiche eseguite utilizzando il connettore Dataflow Apache Beam SpannerIO, REQUEST_TAG contiene un nome di job Dataflow.

Limitazioni

Quando aggiungi tag a letture, query e transazioni, tieni presente le seguenti limitazioni:

La lunghezza di una stringa di tag è limitata a 50 caratteri. Le stringhe che superano questo limite vengono troncate.
In un tag sono consentiti solo i caratteri ASCII (32-126). I caratteri Unicode arbitrari vengono sostituiti da trattini bassi.
Tutti i caratteri di sottolineatura iniziale (_) vengono rimossi dalla stringa.
I tag sono sensibili alle maiuscole. Ad esempio, se aggiungi il tag di richiesta APP=cart,ENV=dev a un insieme di query e app=cart,env=dev a un altro insieme di query, Spanner aggrega le statistiche separatamente per ogni tag.
I tag potrebbero non essere presenti nelle tabelle delle statistiche nelle seguenti circostanze:
- Se Spanner non è in grado di archiviare le statistiche per tutte le operazioni taggate eseguite durante l'intervallo nelle tabelle, il sistema assegna la priorità alle operazioni con le risorse più consumate durante l'intervallo specificato.

Denominazione dei tag

Quando assegni tag alle operazioni del database, è importante considerare le informazioni che vuoi trasmettere in ogni stringa di tag. La convenzione o il pattern che scegli rende i tag più efficaci. Ad esempio, la denominazione corretta dei tag semplifica la correlazione delle statistiche con il codice dell'applicazione.

Puoi scegliere qualsiasi tag entro i limiti indicati. Tuttavia, ti consigliamo di creare una stringa di tag come un insieme di coppie chiave-valore separate da virgole.

Ad esempio, supponiamo di utilizzare un database Spanner per un caso d'uso di e-commerce. Ti consigliamo di includere informazioni sull'applicazione, sull'ambiente di sviluppo e sull'azione intrapresa dalla query nel tag richiesta che assegnerai a una query specifica. Puoi valutare la possibilità di assegnare la stringa del tag nel formato chiave-valore come app=cart,env=dev,action=update. Ciò significa che la query viene chiamata dall'applicazione del carrello nell'ambiente di sviluppo e viene utilizzata per aggiornare il carrello.

Supponiamo che tu abbia un'altra query da un'applicazione di ricerca nel catalogo e che tu assegni la stringa tag come app=catalogsearch,env=dev,action=list. Ora, se una di queste query viene visualizzata nella tabella delle statistiche delle query come query a latenza elevata, puoi identificare l'origine utilizzando il tag.

Ecco alcuni esempi di come un pattern di tagging può essere utilizzato per organizzare le statistiche dell'operazione. Questi esempi non sono esaustivi; puoi anche combinarli nella stringa di tag utilizzando un delimitatore come una virgola.

Chiavi dei tag	Esempi di coppia tag-valore	Descrizione
Applicazione	app=cart app=frontend app=catalogsearch	Aiuta a identificare l'applicazione che chiama l'operazione.
Ambiente	env=prod env=dev env=test env=staging	Consente di identificare l'ambiente associato all'operazione.
Framework	framework=spring framework=django framework=jetty	Aiuta a identificare il framework associato all'operazione.
Azione	action=list action=retrieve action=update	Aiuta a identificare l'azione intrapresa dall'operazione.
Servizio	service=payment service=shipping	Aiuta a identificare il microservizio che chiama l'operazione.

Da tenere presente

Quando assegni un REQUEST_TAG, le statistiche per più query con la stessa stringa di tag vengono raggruppate in una singola riga nella tabella Statistiche query. Nel campo TEXT viene visualizzato solo il testo di una di queste query.
Quando assegni un REQUEST_TAG, le statistiche per più letture con la stessa stringa di tag vengono raggruppate in una singola riga nella tabella delle statistiche di lettura. L'insieme di tutte le colonne lette viene aggiunto al campo READ_COLUMNS.
Quando assegni un TRANSACTION_TAG, le statistiche per le transazioni che hanno la stessa stringa di tag vengono raggruppate in una singola riga nella tabella Statistiche delle transazioni. L'insieme di tutte le colonne scritte dalle transazioni viene aggiunto al campo WRITE_CONSTRUCTIVE_COLUMNS e l'insieme di tutte le colonne lette viene aggiunto al campo READ_COLUMNS.

Scenari di risoluzione dei problemi utilizzando i tag

Gli scenari seguenti descrivono come utilizzare i tag per risolvere i problemi di rendimento.

Trovare l'origine di una transazione problematica

La seguente query restituisce i dati non elaborati per le transazioni principali nel periodo di tempo selezionato.

SELECT
 fprint,
 transaction_tag,
 ROUND(avg_total_latency_seconds,4) as avg_total_latency_sec,
 ROUND(avg_commit_latency_seconds,4) as avg_commit_latency_sec,
 commit_attempt_count,
 commit_abort_count
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE
WHERE interval_end = "2020-05-17T18:40:00"
ORDER BY avg_total_latency_seconds DESC;

La seguente tabella elenca i dati di esempio restituiti dalla nostra query, in cui abbiamo tre applicazioni, ovvero cart, product e frontend, che possiedono o interrogano lo stesso database.

Una volta identificate le transazioni con latenza elevata, puoi utilizzare i tag associati per identificare la parte pertinente del codice dell'applicazione e risolvere ulteriormente i problemi utilizzando le statistiche sulle transazioni.

fprint	transaction_tag	avg_total_latency_sec	avg_commit_latency_sec	commit_attempt_count	commit_abort_count
7129109266372596045	app=cart,service=order	0,3508	0,0139	278802	142205
9353100217060788102	app=cart,service=redis	0,1633	0,0142	129012	27177
9353100217060788102	app=product,service=payment	0,1423	0,0133	5357	636
898069986622520747	app=product,service=shipping	0,0159	0,0118	4269	1
9521689070912159706	app=frontend,service=ads	0,0093	0,0045	164	0
11079878968512225881	[stringa vuota]	0,031	0,015	14	0

Allo stesso modo, il tag richiesta può essere utilizzato per trovare l'origine di una query problematica dalla tabella statistiche query e l'origine di una lettura problematica dalla tabella statistiche lettura.

Trovare la latenza e altre statistiche per le transazioni di una determinata applicazione o microservizio

Se hai utilizzato il nome dell'applicazione o del microservizio nella stringa del tag, puoi filtrare la tabella delle statistiche sulle transazioni in base ai tag che contengono il nome dell'applicazione o del microservizio.

Supponiamo che tu abbia aggiunto nuove transazioni all'app pagamenti e che tu voglia esaminare le latenze e altre statistiche di queste nuove transazioni. Se hai utilizzato il nome dell'applicazione di pagamento all'interno del tag, puoi filtrare la tabella delle statistiche sulle transazioni in modo da visualizzare solo i tag che contengono app=payment.

La seguente query restituisce le statistiche sulle transazioni per l'app di pagamento a intervalli di 10 minuti.

SELECT
  transaction_tag,
  avg_total_latency_sec,
  avg_commit_latency_sec,
  commit_attempt_count,
  commit_abort_count
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE
WHERE STARTS_WITH(transaction_tag, "app=payment")
LIMIT 3;

Ecco un esempio di output:

transaction_tag	avg_total_latency_sec	avg_commit_latency_sec	commit_attempt_count	commit_abort_count
app=payment,action=update	0,3508	0,0139	278802	142205
app=payment,action=transfer	0,1633	0,0142	129012	27177
app=payment, action=retrieve	0,1423	0,0133	5357	636

Allo stesso modo, puoi trovare query o letture da un'applicazione specifica nella tabella Statistiche query o Statistiche letture utilizzando i tag richiesta.

Individuare le transazioni coinvolte nel conflitto di blocco

Per scoprire quali transazioni e chiavi di riga hanno riscontrato tempi di attesa elevati per il blocco, eseguiamo una query sulla tabella LOCK_STAT_TOP_10MINUTE, che elenca le chiavi di riga, le colonne e le transazioni corrispondenti coinvolte nel conflitto di blocco.

SELECT CAST(s.row_range_start_key AS STRING) AS row_range_start_key,
       t.total_lock_wait_seconds,
       s.lock_wait_seconds,
       s.lock_wait_seconds/t.total_lock_wait_seconds frac_of_total,
       s.sample_lock_requests
FROM spanner_sys.lock_stats_total_10minute t, spanner_sys.lock_stats_top_10minute s
WHERE
  t.interval_end = "2020-05-17T18:40:00" and s.interval_end = t.interval_end;

Ecco un esempio di output della nostra query:

row_range_start_key	total_lock_wait_seconds	lock_wait_seconds	frac_of_total	sample_lock_requests
Cantanti(32)	2,37	1,76	1	LOCK_MODE: WriterShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=cart,service=order LOCK_MODE: ReaderShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=cart,service=redis

Da questa tabella dei risultati, possiamo vedere che il conflitto si è verificato nella tabella Singers alla chiave SingerId=32. Singers.SingerInfo è la colonna in cui si è verificato il conflitto di blocco tra ReaderShared e WriterShared. Puoi anche identificare le transazioni corrispondenti (app=cart,service=order e app=cart,service=redis) che presentano il conflitto.

Una volta identificate le transazioni che causano i conflitti di blocco, puoi concentrarti su queste transazioni utilizzando le statistiche sulle transazioni per capire meglio cosa fanno le transazioni e se puoi evitare un conflitto o ridurre il tempo per cui i blocchi vengono mantenuti. Per saperne di più, consulta le best practice per ridurre la contesa dei blocchi.

Passaggi successivi

Scopri di più su altri strumenti di introspezione.
Scopri di più sulle altre informazioni memorizzate da Spanner per ogni database nelle tabelle dello schema informativo del database.
Scopri di più sulle best practice SQL per Spanner.
Scopri di più su come analizzare l'utilizzo elevato della CPU.

Risolvere i problemi relativi ai tag di richiesta e di transazione Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Tag di richiesta

Quando utilizzare i tag di richiesta

Come assegnare i tag alle richieste

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Come visualizzare i tag delle richieste nella tabella delle statistiche

Tag transazione

Quando utilizzare i tag transazione

Come assegnare tag alle transazioni

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Come visualizzare i tag delle transazioni nella tabella delle statistiche delle transazioni

Come visualizzare i tag delle transazioni nella tabella delle statistiche di chiusura

Assegnare automaticamente i tag

Considerazioni per il tagging automatico

Attivare e disattivare il tagging automatico

Regole di priorità della configurazione

Override globali

Configurazione programmatica

Go

Java

Mappatura tra i metodi API e i tag di richiesta e di transazione

Limitazioni

Denominazione dei tag

Da tenere presente

Scenari di risoluzione dei problemi utilizzando i tag

Trovare l'origine di una transazione problematica

Trovare la latenza e altre statistiche per le transazioni di una determinata applicazione o microservizio

Individuare le transazioni coinvolte nel conflitto di blocco

Passaggi successivi

Risolvere i problemi relativi ai tag di richiesta e di transazione