# `Appsignal.Span`
[🔗](https://github.com/appsignal/appsignal-elixir/blob/v2.17.0/lib/appsignal/span.ex#L1)

# `t`

```elixir
@type t() :: %Appsignal.Span{pid: pid(), reference: reference()}
```

# `add_error`

```elixir
@spec add_error(t() | nil, Exception.t(), Exception.stacktrace()) :: t() | nil
```

Add an error to an `Appsignal.Span` by passing an exception from a `rescue`
block, and a stack trace.

## Example
    span = Appsignal.Tracer.root_span()

    try
      raise "Exception!"
    rescue
      exception ->
        Appsignal.Span.add_error(span, exception, __STACKTRACE__)
    end

# `add_error`

```elixir
@spec add_error(t() | nil, Exception.kind(), any(), Exception.stacktrace()) ::
  t() | nil
```

Add an error to an `Appsignal.Span` by passing a `kind` and `reason` from a
`catch` block, and a stack trace.

## Example
    span = Appsignal.Tracer.root_span()

    try
      raise "Exception!"
    catch
      kind, reason ->
        Appsignal.Span.add_error(span, kind, reason, __STACKTRACE__)
    end

# `close`

```elixir
@spec close(t() | nil) :: t() | nil
```

Close an `Appsignal.Span`.

## Example
    Appsignal.Tracer.root_span()
    |> Span.close()

# `close`

```elixir
@spec close(t() | nil, integer()) :: t() | nil
```

Close an `Appsignal.Span` with an explicit end time.

## Example
    Appsignal.Tracer.root_span()
    |> Span.close(span, :os.system_time())

# `create_child`

```elixir
@spec create_child(t() | nil, pid()) :: t() | nil
```

Create a child `Appsignal.Span`.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.create_child(self())

# `create_child`

```elixir
@spec create_child(t() | nil, pid(), integer() | nil) :: t() | nil
```

Create a child `Appsignal.Span` with an explicit start time.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.create_child(self(), :os.system_time())

# `create_root`

```elixir
@spec create_root(String.t(), pid()) :: t() | nil
```

Create a root `Appsignal.Span` with a namespace and a pid.

For a description of namespaces, see `set_namespace/2`.

## Example
    Appsignal.Span.create_root("http_request", self())

# `create_root`

```elixir
@spec create_root(String.t(), pid(), integer() | nil) :: t() | nil
```

Create a root `Appsignal.Span` with a namespace, a pid and an explicit start time.

For a description of namespaces, see `set_namespace/2`.

## Example
    Appsignal.Span.create_root("http_request", self(), :os.system_time())

# `set_attribute`

```elixir
@spec set_attribute(
  t() | nil,
  String.t(),
  String.t() | integer() | boolean() | float()
) :: t() | nil
```

Sets an `Appsignal.Span` attribute.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_attribute("appsignal:category", "query.ecto")

# `set_name`

```elixir
@spec set_name(t() | nil, String.t()) :: t() | nil
```

Sets an `Appsignal.Span`'s name.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_name("PageController#index")

# `set_name_if_nil`

```elixir
@spec set_name_if_nil(t() | nil, String.t()) :: t() | nil
```

Sets an `Appsignal.Span`'s name if it was not set before.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_name_if_nil("PageController#index")

# `set_namespace`

```elixir
@spec set_namespace(t() | nil, String.t()) :: t() | nil
```

Sets an `Appsignal.Span`'s namespace.  The namespace is `"http_request"` or
`"background_job'` to add the span to the "web" and "background" namespaces
respectively. Passing another string creates a custom namespace to store the
`Appsignal.Span`'s samples in.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_namespace("http_request")

# `set_namespace_if_nil`

```elixir
@spec set_namespace_if_nil(t() | nil, String.t()) :: t() | nil
```

Sets an `Appsignal.Span`'s namespace.  The namespace is `"http_request"` or
`"background_job'` to add the span to the "web" and "background" namespaces
respectively. Passing another string creates a custom namespace to store the
`Appsignal.Span`'s samples in.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_namespace("http_request")

# `set_sample_data`

```elixir
@spec set_sample_data(t() | nil, String.t(), map()) :: t() | nil
```

Sets sample data for an `Appsignal.Span`.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_sample_data("environment", %{"method" => "GET"})

# `set_sample_data_if_nil`

```elixir
@spec set_sample_data_if_nil(t() | nil, String.t(), map()) :: t() | nil
```

Sets sample data for an `Appsignal.Span`, unless it has already been set.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_sample_data_if_nil("environment", %{"method" => "GET"})

# `set_sql`

```elixir
@spec set_sql(t() | nil, String.t()) :: t() | nil
```

Sets the `"appsignal:body"` attribute with an SQL query string.

## Example
    Appsignal.Tracer.root_span()
    |> Appsignal.Span.set_sql("SELECT * FROM users")

---

*Consult [api-reference.md](api-reference.md) for complete listing*