---
title: add_custom_span_attribute (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/addcustomspanattribute-python-agent-api
---

## Syntax

```py
newrelic.agent.add_custom_span_attribute(key, value)
```

Adds a custom attribute to a span event.

## Description

This call records a [custom attribute](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#attribute) (a key/value pair attached to your [span event](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary#span)).

Attributes may be found in Distributed Tracing or in APM if a transaction trace is created by the parent transaction. Attributes can also be [found and queried](https://docs.newrelic.com/docs/query-your-data/explore-query-data/explore-data/introduction-querying-new-relic-data) in the New Relic UI.

> #### ⚠️ IMPORTANT
>
> Before you create custom attributes, review our list of [reserved terms used by NRQL](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words).

## Parameters

| Parameter                                       | Description                                                                                              |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `key` _string_                                  | Required. The key name. Only the first 255 characters are retained.                                      |
| `value` _string_, _integer_, _float_, _boolean_ | Required. The string value to add to the current span event. Only the first 255 characters are retained. |

## Return values

Returns `True` if attribute was added successfully. 

## Examples

### Adding custom attributes to background task [#custom-parameter-example]

An example of adding custom attributes to a [background task](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/background_task):

```py
@newrelic.agent.background_task()
def send_request():
    with newrelic.agent.FunctionTrace(name='Trace'):
        newrelic.agent.add_custom_span_attribute('attribute', 'value')
```

### Using custom span attribute to troubleshoot [#parameter-troubleshooting]

You can also use custom attributes to troubleshoot performance issues. For example, you might see occasional slow response times from a pool of memcache instances, but you don't know what instance is causing the problem. You might add an attribute to the span indicating the server, like so:

```py
# Set server_ip to be the current server processing the transaction

newrelic.agent.add_custom_span_attribute("memcache_query_frontend_lookup", server_ip)
```