> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/active-directory.md).

# Active Directory

The Active Directory source collects telemetry from a Microsoft Active Directory Domain Services (AD DS) domain controller. It gathers AD DS metrics from Windows performance counters (replication, LDAP, and directory service activity) and reads AD DS-related event logs for DNS Server, DFS Replication, and File Replication. This source runs only on the Windows domain controller itself.

### Supported Telemetry

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| Windows  | ✓       | ✓    |        |

### Prerequisites

* A Windows host that is a promoted Active Directory Domain Services domain controller. The metrics receiver reads AD DS performance counters that only exist on a domain controller.
* The Bindplane agent must run on the domain controller. This source cannot collect AD DS data remotely.
* The agent service account needs permission to read the relevant Windows Event Log channels (`DNS Server`, `DFS Replication`, and `File Replication Service`) for the log types you enable.
* DNS Server, DFS Replication, and File Replication logs are only present when those roles or services are installed and running on the domain controller. Disable the corresponding log toggle for any role that is not installed.

For background on AD DS performance counters and monitoring, see [Troubleshoot Active Directory Domain Services performance](https://learn.microsoft.com/en-us/windows-server/administration/performance-tuning/role/active-directory-server/troubleshoot) on Microsoft Learn.

### Configuration

<figure><img src="/files/FoZDcXE3izPweQhlWD1R" alt="Bindplane docs - Active Directory - image 1"><figcaption></figcaption></figure>

**Telemetry**

| Parameter             | Type               | Required | Default           | Description                                                                                                                                                                             |
| --------------------- | ------------------ | -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose Telemetry Type | Telemetry Selector | No       | `Logs`, `Metrics` | Which signals this source collects. Valid values are `Logs` and `Metrics`. Metrics parameters apply only when `Metrics` is selected; log parameters apply only when `Logs` is selected. |

**Logs**

| Parameter             | Type    | Required | Default | Description                                  |
| --------------------- | ------- | -------- | ------- | -------------------------------------------- |
| DNS Server Logs       | Boolean | No       | `true`  | Collect AD DS DNS Server event logs.         |
| DFS Replication Logs  | Boolean | No       | `true`  | Collect DFS Replication event logs.          |
| File Replication Logs | Boolean | No       | `false` | Collect File Replication Service event logs. |

**Advanced**

| Parameter           | Type    | Required | Default | Description                                                                                                                         |
| ------------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Collection Interval | Integer | No       | `60`    | How often, in seconds, to scrape metrics. Applies when `Metrics` is selected.                                                       |
| Start At            | Enum    | No       | `end`   | Where to begin reading logs: `beginning` reads existing log records, `end` reads only new records. Applies when `Logs` is selected. |
| Parse               | Boolean | No       | `false` | Parse the log fields into structured data. Applies when `Logs` is selected.                                                         |

### Examples

#### Metrics only, faster scrape

Collect AD DS performance-counter metrics every 30 seconds and skip log collection.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: active-directory
spec:
  type: microsoftactivedirectory
  parameters:
    - name: telemetry_types
      value:
        - Metrics
    - name: collection_interval
      value: 30
```

#### Logs only, DNS and DFS replication

Collect DNS Server and DFS Replication logs, leave File Replication off, and read only new records.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: active-directory
spec:
  type: microsoftactivedirectory
  parameters:
    - name: telemetry_types
      value:
        - Logs
    - name: enable_dns_server
      value: true
    - name: enable_dfs_replication
      value: true
    - name: enable_file_replication
      value: false
    - name: start_at
      value: end
```

### Configuration Tips

* Turn off any log toggle for a role the domain controller does not run. Enabling File Replication Logs on a server using DFS Replication (the modern default) produces no records.
* Set Start At to `beginning` only for a one-time backfill. Leaving it at `end` avoids re-ingesting historical events on every agent restart.
* Enable Parse to get structured fields from the AD DS log records instead of a single raw message body.

### Troubleshooting

#### No metrics appear

Symptoms: the source reports no AD DS metrics.

Solutions:

1. Confirm the agent runs on a promoted domain controller. The `active_directory_ds` performance counters do not exist on member servers or non-AD hosts.
2. Confirm `Metrics` is selected in Choose Telemetry Type.

#### No logs for an enabled type

Symptoms: a log toggle is on but no records arrive.

Solutions:

1. Verify the corresponding role or service is installed and writing to its event channel (`DNS Server`, `DFS Replication`, or `File Replication Service`).
2. Set Start At to `beginning` to confirm whether any historical records exist, then return it to `end`.
3. Confirm the agent service account can read the relevant Windows Event Log channels.

### Standalone Source

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: active-directory
spec:
  type: microsoftactivedirectory
  parameters:
    - name: telemetry_types
      value:
        - Logs
        - Metrics
    - name: collection_interval
      value: 60
    - name: enable_dns_server
      value: true
    - name: enable_dfs_replication
      value: true
    - name: enable_file_replication
      value: false
    - name: start_at
      value: end
    - name: parse
      value: false
```

### Related Resources

* [Active Directory Domain Services Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/activedirectorydsreceiver)
* [Troubleshoot Active Directory Domain Services performance (Microsoft Learn)](https://learn.microsoft.com/en-us/windows-server/administration/performance-tuning/role/active-directory-server/troubleshoot)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/active-directory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.