> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Attributes & Tags

> Enriching traces with metadata

## Overview

**Attributes** and **tags** are two ways to add metadata to traces:

* **Attributes**: Key-value pairs for detailed, queryable data
* **Tags**: Simple labels for categorization and filtering

## Attributes

### Adding Single Attributes

```typescript theme={null}
trace.addAttribute('userId', 'user-123')
     .addAttribute('amount', 1.5)
     .addAttribute('currency', 'ETH');
```

### Adding Multiple Attributes

```typescript theme={null}
trace.addAttributes({
  from: '0xabc...',
  to: '0xdef...',
  value: '1.5',
  gasLimit: 21000
});
```

### Complex Values

Objects are automatically stringified to JSON:

```typescript theme={null}
trace.addAttribute('config', {
  slippage: 0.5,
  deadline: 300,
  route: ['ETH', 'USDC', 'DAI']
});
// Stored as: '{"slippage":0.5,"deadline":300,"route":["ETH","USDC","DAI"]}'
```

### Common Attribute Patterns

```typescript theme={null}
// User context
trace.addAttributes({
  userId: user.id,
  walletAddress: user.wallet,
  sessionId: session.id
});

// Transaction details
trace.addAttributes({
  txHash: receipt.hash,
  blockNumber: receipt.blockNumber,
  gasUsed: receipt.gasUsed.toString()
});

// Operation parameters
trace.addAttributes({
  inputToken: 'ETH',
  outputToken: 'USDC',
  inputAmount: '1.5',
  slippage: '0.5%'
});
```

## Tags

### Adding Single Tags

```typescript theme={null}
trace.addTag('ethereum')
     .addTag('swap')
     .addTag('production');
```

### Adding Multiple Tags

```typescript theme={null}
trace.addTags(['dex', 'uniswap', 'v3']);
```

### Tag Use Cases

Tags are ideal for:

* **Chain identification**: `ethereum`, `polygon`, `arbitrum`
* **Operation type**: `swap`, `transfer`, `mint`, `stake`
* **Environment**: `production`, `staging`, `development`
* **Feature flags**: `beta`, `experimental`
* **Priority**: `critical`, `high`, `normal`

```typescript theme={null}
const trace = client.trace({ name: 'NFTMint' })
  .addTags(['nft', 'mint', 'ethereum', 'production']);
```

## Attributes vs Tags

| Aspect       | Attributes              | Tags               |
| ------------ | ----------------------- | ------------------ |
| Structure    | Key-value pairs         | Simple strings     |
| Use case     | Detailed data           | Categorization     |
| Queryability | Filter by key and value | Filter by presence |
| Example      | `userId: "123"`         | `"ethereum"`       |

### When to Use Attributes

* Specific values you'll query: user IDs, amounts, addresses
* Data that varies per trace: transaction hashes, block numbers
* Structured information: configuration objects

### When to Use Tags

* Categories that group traces: chain names, operation types
* Boolean-like flags: is this production? is this a swap?
* Simple labels for filtering dashboards

## Method Signatures

### Attributes

```typescript theme={null}
addAttribute(key: string, value: string | number | object): Trace
addAttributes(attrs: Record<string, string | number | object>): Trace
```

### Tags

```typescript theme={null}
addTag(tag: string): Trace
addTags(tags: string[]): Trace
```

## Best Practices

### Be Consistent with Keys

Use a consistent naming convention:

```typescript theme={null}
// Good - consistent camelCase
trace.addAttributes({
  userId: '123',
  walletAddress: '0x...',
  transactionHash: '0x...'
});

// Avoid - mixed conventions
trace.addAttributes({
  user_id: '123',
  WalletAddress: '0x...',
  'transaction-hash': '0x...'
});
```

### Don't Store Sensitive Data

Avoid including private keys, passwords, or PII:

```typescript theme={null}
// Good
trace.addAttribute('walletAddress', publicAddress);

// Never do this
trace.addAttribute('privateKey', wallet.privateKey);
```

### Use Meaningful Tag Names

Tags should be immediately understandable:

```typescript theme={null}
// Good
trace.addTags(['ethereum', 'swap', 'uniswap']);

// Avoid
trace.addTags(['eth', 'sw', 'uni']);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Transaction Hints" icon="cube" href="/concepts/transaction-hints">
    Correlate traces with blockchain transactions
  </Card>

  <Card title="Browser Metadata" icon="browser" href="/advanced/browser-metadata">
    Automatic environment data collection
  </Card>
</CardGroup>