Skip to content

Fixes #108, #111, #99 #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
root = true

[*]
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4

[*.{csproj,json,config,yml}]
indent_size = 2

[*.sh]
end_of_line = lf

[*.{cmd, bat}]
end_of_line = crlf
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -183,3 +183,4 @@ UpgradeLog*.htm
FakesAssemblies/
/.vs/serilog-sinks-mssqlserver/v15/sqlite3
/.vs/serilog-sinks-mssqlserver/v15/Server/sqlite3
/.vs
147 changes: 129 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,19 @@
A Serilog sink that writes events to Microsoft SQL Server. While a NoSql store allows for more flexibility to store the different kinds of properties, it sometimes is easier to use an already existing MS SQL server. This sink will write the logevent data to a table and can optionally also store the properties inside an Xml column so they can be queried.

**Package** - [Serilog.Sinks.MSSqlServer](http://nuget.org/packages/serilog.sinks.mssqlserver)
| **Platforms** - .NET 4.5 and .NET Standard 2.0
| **Platforms** - .NET Framework 4.5 and .NET Standard 2.0

## Configuration

At minimum a connection string and table name are required.
At minimum a connection string and table name are required.

To use a connection string from the `<connectionStrings>` element of your application config file, specify its name as the value of the connection string.
To use a connection string from the `connectionStrings` section of your application config, specify its name as the value of the connection string.

#### Code

#### Code (.NET Framework)

```csharp
var connectionString = @"Server=..."; // or the name of a connection string in your .config file
var connectionString = @"Server=..."; // or the name of a connection string in the app config
var tableName = "Logs";
var columnOptions = new ColumnOptions(); // optional

Expand All @@ -23,9 +24,30 @@ var log = new LoggerConfiguration()
.CreateLogger();
```

#### XML

If you are configuring Serilog with the `ReadFrom.AppSettings()` XML configuration support, you can use:
#### Code (.NET Standard / .NET Core)

The application configuration parameter is optional for .NET Standard libraries or .NET Core applications:

```csharp
var appSettings = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json")
.Build(); // more likely you will inject an IConfiguration reference

var connectionString = @"Server=..."; // or the name of a connection string in the app config
var tableName = "Logs";
var columnOptions = new ColumnOptions(); // optional

var log = new LoggerConfiguration()
.WriteTo.MSSqlServer(connectionString, tableName, appConfiguration: appSettings, columnOptions: columnOptions)
.CreateLogger();
```


#### Serilog AppSettings package (.NET Framework)

.NET Framework libraries or applications can call `ReadFrom.AppSettings()` to configure Serilog using the [Serilog.Settings.AppSettings](https://github.com/serilog/serilog-settings-appsettings) package. This will apply configuration parameters from the `app.config` or `web.config` file:

```xml
<add key="serilog:using:MSSqlServer" value="Serilog.Sinks.MSSqlServer" />
Expand All @@ -34,6 +56,29 @@ If you are configuring Serilog with the `ReadFrom.AppSettings()` XML configurati
<add key="serilog:write-to:MSSqlServer.autoCreateSqlTable" value="true"/>
```


#### Serilog Configuration package (.NET Standard / .NET Core)

.NET Standard libraries and .NET Core applications can call `ReadFrom.Configuration(IConfiguration)` to configure Serilog using the [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) package. This will apply configuration parameters from the application configuration (not only `appsettings.json` as shown here, but any other valid `IConfiguration` source):

```json
{
"Serilog": {
"Using": ["Serilog.Sinks.MSSqlServer"],
"MinimumLevel": "Debug",
"WriteTo": [
{ "Name": "MSSqlServer",
"Args": {
"connectionString": "Server...",
"tableName": "Logs"
}
}
]
}
}
```


## Table definition

You'll need to create a table like this in your database:
Expand Down Expand Up @@ -73,15 +118,15 @@ If you set the `autoCreateSqlTable` option to `true`, the sink will create a tab

## Standard columns

The "standard columns" used by this sink (apart from obvious required columns like Id) are described by the StandardColumn enumeration and controlled by `columnOptions.Store`.
The "standard columns" used by this sink (apart from obvious required columns like Id) are described by the StandardColumn enumeration and controlled through code by the `columnOptions.Store` collection.

By default (and consistent with the SQL command to create a table, above) these columns are included:
- StandardColumn.Message
- StandardColumn.MessageTemplate
- StandardColumn.Level
- StandardColumn.TimeStamp
- StandardColumn.Exception
- StandardColumn.Properties
- `StandardColumn.Message`
- `StandardColumn.MessageTemplate`
- `StandardColumn.Level`
- `StandardColumn.TimeStamp`
- `StandardColumn.Exception`
- `StandardColumn.Properties`

You can change this list, as long as the table definition is consistent:

Expand Down Expand Up @@ -120,14 +165,14 @@ The log event properties `User` and `Other` will now be placed in the correspond

#### Excluding redundant items from the Properties column

By default, additional properties will still be included in the XML data saved to the Properties column (assuming that is not disabled via the `columnOptions.Store` parameter). This is consistent with the idea behind structured logging, and makes it easier to convert the log data to another (e.g. NoSQL) storage platform later if desired.
By default, additional properties will still be included in the data saved to the XML Properties or JSON LogEvent column (assuming one or both are enabled via the `columnOptions.Store` parameter). This is consistent with the idea behind structured logging, and makes it easier to convert the log data to another (e.g. NoSQL) storage platform later if desired.

However, if necessary, then the properties being saved in their own columns can be excluded from the XML. Use the `columnOptions.Properties.ExcludeAdditionalProperties` parameter in the sink configuration to exclude the redundant properties from the XML.
However, if necessary, then the properties being saved in their own columns can be excluded from the data. Use the `columnOptions.Properties.ExcludeAdditionalProperties` parameter in the sink configuration to exclude the redundant properties from the XML.


### XML configuration for columns
### Columns defined by AppSettings (.NET Framework)

Columns can be defined with the name and data type of the column in SQL Server. Columns specified must match database table exactly. DataType is case sensitive, based on SQL type (excluding precision/length).
Custom columns can be defined with the name and data type of the column in SQL Server. Columns specified must match database table exactly. DataType is case sensitive, based on SQL type (excluding precision/length). This section will be processed automatically if it exists in the application's `web.config` or `app.config` file.

```xml
<configSections>
Expand All @@ -142,6 +187,72 @@ Columns can be defined with the name and data type of the column in SQL Server.
</MSSqlServerSettingsSection>
```

### ColumnOptions defined by Configuration (.NET Standard / .NET Core)

For projects using the Serilog Configuration package, most properties of the `ColumnOptions` object are configurable. (The only property not currently supported is the filter-predicate `columnOptions.Properties.PropertyFilter`).

The equivalent of adding custom columns as shown in the .NET Framework example above looks like this:

```json
{
"Serilog": {
"Using": ["Serilog.Sinks.MSSqlServer"],
"MinimumLevel": "Debug",
"WriteTo": [
{ "Name": "MSSqlServer",
"Args": {
"connectionString": "Server...",
"tableName": "Logs",
"columnOptionsSection": {
"customColumns": [
{ "ColumnName": "EventType", "DataType": "int" },
{ "ColumnName": "Release", "DataType": "varchar" }
]
}
}
}
]
}
}
```

As the name suggests, `columnOptionSection` is an entire configuration section in its own right. All possible entries and some sample values are shown below. All properties and subsections are optional.

```json
"columnOptionsSection": {
"addStandardColumns": [ "LogEvent" ],
"removeStandardColumns": [ "MessageTemplate", "Properties" ],
"customColumns": [
{ "ColumnName": "EventType", "DataType": "int" },
{ "ColumnName": "Release", "DataType": "varchar" }
],
"disableTriggers": true,
"id": { "columnName": "Id" },
"level": { "columnName": "Level", "storeAsEnum": false },
"properties": {
"columnName": "Properties",
"excludeAdditionalProperties": true,
"dictionaryElementName": "dict",
"itemElementName": "item",
"omitDictionaryContainerElement": false,
"omitSequenceContainerElement": false,
"omitStructureContainerElement": false,
"omitElementIfEmpty": true,
"propertyElementName": "prop",
"rootElementName": "root",
"sequenceElementName": "seq",
"structureElementName": "struct",
"usePropertyKeyAsElementName": false
},
"timeStamp": { "columnName": "Timestamp", "convertToUtc": true },
"logEvent": { "columnName": "LogEvent", "excludeAdditionalProperties": true }
"message": { "columnName": "Message" },
"exception": { "columnName": "Exception" },
"messageTemplate": { "columnName": "MessageTemplate" },
}
```


### Options for serialization of the log event data

#### JSON (LogEvent column)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.

using System.Configuration;

namespace Serilog.Configuration
{
using System;
using System.Configuration;

/// <summary>
/// Collection of configuration items for use in generating DataColumn[]
/// </summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.

using System.Configuration;

namespace Serilog.Configuration
{
using System;
using System.Configuration;

/// <summary>
///
/// </summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,18 @@
// See the License for the specific language governing permissions and
// limitations under the License.

using Serilog.Sinks.MSSqlServer;
using System.Configuration;

namespace Serilog.Configuration
{
using System;
using System.Configuration;

/// <summary>
/// Settings configuration for defining DataColumns collection
/// </summary>
public class MSSqlServerConfigurationSection : ConfigurationSection
{
private static MSSqlServerConfigurationSection settings =
ConfigurationManager.GetSection("MSSqlServerSettings") as MSSqlServerConfigurationSection;
ConfigurationManager.GetSection("MSSqlServerSettingsSection") as MSSqlServerConfigurationSection;

/// <summary>
/// Access to the settings stored in the config file
Expand Down
Loading